TuckerTensorTrain#

class t3toolbox.tucker_tensor_train.TuckerTensorTrain#

Tucker tensor train with non-uniform (ragged) shape and ranks.

Tensor network diagram for a TuckerTensorTrain with d free indices:

    r0        r1        r2       r(d-1)          rd
1 ------ G0 ------ G1 ------ ... ------ G(d-1) ------ 1
         |         |                    |
         | n0      | n1                 | nd
         |         |                    |
         B0        B1                   B(d-1)
         |         |                    |
         | N0      | N1                 | Nd
         |         |                    |

Cores:#

The TuckerTensorTrain is defined by its cores:

  • tucker_cores: Tuple[NDArray,…]

    tucker_cores = (B0, ..., B(d-1)), Bi.shape=stack_shape+(ni, Ni)

  • tt_cores: Tuple[NDArray,…]

    tt_cores = (G0, ..., G(d-1)), Gi.shape=stack_shape+(ri, ni, r(i+1))

Example:

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = (np.zeros((4,14)), np.zeros((5,15)), np.zeros((6,16)))
>>> tt_cores = (np.zeros((1,4,3)), np.zeros((3,5,2)), np.zeros((2,6,1)))
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores) # TuckerTensorTrain, cores filled with zeros
>>> print(x.core_shapes)
(((4, 14), (5, 15), (6, 16)), ((1, 4, 3), (3, 5, 2), (2, 6, 1)))
>>> print(x.data == (tucker_cores, tt_cores))
True

Shape and ranks:#

The structure of a Tucker tensor train is defined by its shape and ranks:

  • shape: Tuple[int,…]

    shape = (N0, N1, ..., N(d-1))

  • tucker_ranks: Tuple[int,…]

    tucker_ranks = (n0, r1, ..., n(d-1))

  • tt_ranks: Tuple[int,…]

    tt_ranks = (r0, r1, ..., rd)

  • stack_shape: Tuple[int,…]

    (optional, more on this below)

Often, the first and last TT-ranks satisfy r0=rd=1, and “1” in the diagram is the number 1. However, it is allowed for these ranks to not be 1, in which case the “1”s in the diagram are vectors of ones. You can make r0=rd=1 using squash_tails().

Example:

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = (np.zeros((4,14)), np.zeros((5,15)), np.zeros((6,16)))
>>> tt_cores = (np.zeros((1,4,3)), np.zeros((3,5,2)), np.zeros((2,6,1)))
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores) # TuckerTensorTrain, cores filled with zeros
>>> print(x.d)
3
>>> print(x.shape)
(14, 15, 16)
>>> print(x.tucker_ranks)
(4, 5, 6)
>>> print(x.tt_ranks)
(1, 3, 2, 1)

Stacking:#

Many stacked Tucker tensor trains with the same shape and ranks may be stored in this object for vectorized operations. In this case,

  • tucker_cores[ii].shape=stack_shape+(ni,Ni)

  • tt_cores[ii].shape=stack_shape+(ri, ni, r(i+1))

If no stacking is used, then stack_shape=().

Operations that use a numerical tolerance (rtol or atol) cannot be used with stacked TuckerTensorTrains because the shape of the results could vary between different elements of the stack.

Examples:

Create a stacked TuckerTensorTrain from stacked core arrays:

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = [np.ones((6,7, 4,14)),np.ones((6,7, 5,15)),np.ones((6,7, 6,16))]
>>> tt_cores = [np.ones((6,7, 1,4,3)), np.ones((6,7, 3,5,2)), np.ones((6,7, 2,6,1))]
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores) # TuckerTensorTrain, cores filled with ones
>>> print(x.stack_shape)
(6, 7)
>>> print(x.structure)
((14, 15, 16), (4, 5, 6), (1, 3, 2, 1), (6, 7))

Create a stacked TuckerTensorTrain by stacking several TuckerTensorTrains:

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> x00 = t3.TuckerTensorTrain.randn((13,14,15), (4,5,6), (2,8,9,3))
>>> x01 = t3.TuckerTensorTrain.randn((13,14,15), (4,5,6), (2,8,9,3))
>>> x10 = t3.TuckerTensorTrain.randn((13,14,15), (4,5,6), (2,8,9,3))
>>> x11 = t3.TuckerTensorTrain.randn((13,14,15), (4,5,6), (2,8,9,3))
>>> print([B.shape for B in x00.tucker_cores])
[(4, 13), (5, 14), (6, 15)]
>>> print([G.shape for G in x00.tt_cores])
[(2, 4, 8), (8, 5, 9), (9, 6, 3)]
>>> print(x00.stack_shape)
()
>>> x_stacked = t3.TuckerTensorTrain.stack([[x00, x01], [x10, x11]])
>>> print([B.shape for B in x_stacked.tucker_cores])
[(2, 2, 4, 13), (2, 2, 5, 14), (2, 2, 6, 15)]
>>> print([G.shape for G in x_stacked.tt_cores])
[(2, 2, 2, 4, 8), (2, 2, 8, 5, 9), (2, 2, 9, 6, 3)]
>>> print(x_stacked.stack_shape)
(2, 2)

Using rtol option in t3svd() yields an error for stacked TuckerTensorTrains

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> x = t3.TuckerTensorTrain.randn((13,14,15), (4,5,6), (2,8,9,3))
>>> result = x.t3svd() # OK
>>> result = x.t3svd(rtol=1e-2) # OK
>>> x = t3.TuckerTensorTrain.randn((13,14,15), (4,5,6), (2,8,9,3), stack_shape=(2,3))
>>> result = x.t3svd() # OK
>>> result = x.t3svd(rtol=1e-2) # Error!
Traceback (most recent call last):
    ...
ValueError

Minimal ranks:#

Tucker tensor train ranks are minimal if they satisfy the following conditions,

  • r(i+1) <= (ri*ni) for i=1,...,d

  • ri <= (ni*r(i+1)) for i=1,...,d

  • ni <= (ri*r(i+1)) for i=1,...,d

  • ni <= Ni for i=1,...,d

The first three conditions say that the product of any two dimensions of a TT core is at least as large as the other dimension. The last condition says that the Tucker ranks are less than the tensor shape.

Here, minimal ranks are defined with respect to a generic Tucker tensor train with the given shape and rank structure. We do not account for numerical rank deficiency.

Minimal ranks always exist and are unique.

  • Minimal TT ranks are equal to the ranks of (N0*...*Ni) x (N(i+1)*...*N(d-1)) matrix unfoldings.

  • Minimal Tucker ranks are equal to the ranks of Ni x (N0*...*N(i-1)*N(i+1)*...*N(d-1)) matricizations.

More details on the connection between minimal ranks and unfoldings/matricizations are given in Section 2.3 of [1].

Example:

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> x = t3.TuckerTensorTrain.randn((13,14,15,16), (4,99,6,7), (1,4,9,7,1)) # random T3
>>> print(x.ranks)
((4, 99, 6, 7), (1, 4, 9, 7, 1))
>>> print(x.minimal_ranks)
((4, 14, 6, 7), (1, 4, 9, 7, 1))
>>> print(x.has_minimal_ranks)
False
>>> x = t3.TuckerTensorTrain.randn((13,14,15,16), (4,5,6,7), (1,4,9,7,1))
>>> print(x.has_minimal_ranks)
True
>>> x = t3.TuckerTensorTrain.zeros((13,14,15,16), (4,5,6,7), (1,4,9,7,1)) # T3 filled with zeros
>>> print(x.has_minimal_ranks) # minimal ranks depends on structural ranks, not numerical ranks
True

Making a TuckerTensorTrain have minimal ranks using t3svd():

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> x = t3.TuckerTensorTrain.randn((13,14,15,16), (4,5,6,7), (1,99,9,7,1))
>>> print(x.has_minimal_ranks)
False
>>> print(x.minimal_ranks)            # the inflated TT bond 99 is structurally minimal at 4
((4, 5, 6, 7), (1, 4, 9, 7, 1))
>>> x2, _, _ = x.t3svd()
>>> print(x2.has_minimal_ranks)
True

Tensor linear algebra:#

Linear algebra operations (addition, subtraction, multiplication, negation, inner products, norms, summing over axes) are mathematically defined with respect to the N0 x ... x N(d-1) dense tensors represented by the Tucker tensor trains. These operations are performed implicitly using Tucker tensor train cores as a computational device, because the dense tensors can be extremely large. The results faithfully represent what one would have gotten if one performed the operations on the dense tensors. E.g.: .. math:: (x + y).to_dense() = x.to_dense() + y.to_dense()

Adding Tucker tensor trains adds their ranks, and multiplication multiplies their ranks. To prevent ranks growing too large when many linear algebra operations are performed in sequence, it may be useful to perform truncated T3SVDs between operations (using either max_tucker_ranks, rtol, or atol as parameters in t3svd()).

For corewise operations, see t3toolbox.corewise

Examples:

Add two TuckerTensorTrains

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> x = t3.TuckerTensorTrain.randn((13,14,15,16), (4,5,6,7), (2,8,9,7,3))
>>> y = t3.TuckerTensorTrain.randn((13,14,15,16), (9,8,7,6), (1,2,3,4,5))
>>> print(np.allclose((x + y).to_dense(), x.to_dense() + y.to_dense()))
True

A more complicated linear algebra operation with three TuckerTensorTrains

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> x = t3.TuckerTensorTrain.randn((13,14,15,16), (2,3,4,3), (1,2,4,3,2))
>>> y = t3.TuckerTensorTrain.randn((13,14,15,16), (4,3,5,1), (4,3,2,1,2))
>>> z = t3.TuckerTensorTrain.randn((13,14,15,16), (1,2,3,4), (1,2,3,4,5))
>>> result = (x * (y * 2.4 + z)).inner(z) + (x - y).norm() + z.sum()
>>> X, Y, Z = x.to_dense(), y.to_dense(), z.to_dense()
>>> result2 = np.einsum('ijkl,ijkl', (X * (Y * 2.4 + Z)), Z) + np.linalg.norm(X - Y) + Z.sum()
>>> print(np.allclose(result, result2))
True

References

tucker_cores: Tuple[NDArray, Ellipsis]#

Tucker cores for the TuckerTensorTrain.

  • tucker_cores=(B0, ..., B(d-1)).

  • len(tucker_cores)=d,

  • tucker_cores[ii]=stack_shape+(ni, Ni).

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = (np.zeros((4,14)), np.zeros((5,15)), np.zeros((6,16)))
>>> tt_cores = (np.zeros((1,4,3)), np.zeros((3,5,2)), np.zeros((2,6,1)))
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores)
>>> print(x.tucker_cores == tucker_cores)
True
tt_cores: Tuple[NDArray, Ellipsis]#

TT cores for the TuckerTensorTrain.

  • tt_cores=(G0, ..., G(d-1)).

  • len(tt_cores)=d,

  • tt_cores[ii]=stack_shape+(ri, ni, r(i+1)).

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = (np.zeros((4,14)), np.zeros((5,15)), np.zeros((6,16)))
>>> tt_cores = (np.zeros((1,4,3)), np.zeros((3,5,2)), np.zeros((2,6,1)))
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores)
>>> print(x.tt_cores == tt_cores)
True
property data: Tuple[Tuple[NDArray, Ellipsis], Tuple[NDArray, Ellipsis]]#

Tuple containing the Tucker cores and TT cores. data=(tucker_cores, tt_cores)

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = (np.ones((4,14)),np.ones((5,15)),np.ones((6,16)))
>>> tt_cores = (np.ones((1,4,3)), np.ones((3,5,2)), np.ones((2,6,1)))
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores)
>>> print(x.data == (tucker_cores, tt_cores))
True
Return type:

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

property d: int#

Number of indices of the tensor. d=len(tucker_cores)=len(tt_cores)

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = (np.zeros((4,14)), np.zeros((5,15)), np.zeros((6,16)))
>>> tt_cores = (np.zeros((1,4,3)), np.zeros((3,5,2)), np.zeros((2,6,1)))
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores)
>>> print(x.d)
3
>>> tucker_cores = (np.zeros((4,14)), np.zeros((5,15)))
>>> tt_cores = (np.zeros((1,4,3)), np.zeros((3,5,2)))
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores)
>>> print(x.d)
2
Return type:

int

property stack_shape: Tuple[int, Ellipsis]#

If this object contains multiple stacked T3s with the same structure, this is the shape of the stack. If no stacking is used then stack_shape=().

  • tucker_cores[ii].shape  = stack_shape+(ni, Ni)

  • tt_cores[ii].shape      = stack_shape+(ri, ni, r(i+1))

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = [np.zeros((4,14)),np.zeros((5,15)), np.zeros((6,16))]
>>> tt_cores = [np.zeros((1,4,3)), np.zeros((3,5,2)), np.ones((2,6,1))]
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores)
>>> print(x.stack_shape)
()
>>> tucker_cores = [np.zeros((6, 4,14)),np.zeros((6, 5,15)), np.zeros((6, 6,16))]
>>> tt_cores = [np.zeros((6, 1,4,3)), np.zeros((6, 3,5,2)), np.ones((6, 2,6,1))]
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores)
>>> print(x.stack_shape)
(6,)
>>> tucker_cores = [np.zeros((6,7, 4,14)),np.zeros((6,7, 5,15)), np.zeros((6,7, 6,16))]
>>> tt_cores = [np.zeros((6,7, 1,4,3)), np.zeros((6,7, 3,5,2)), np.ones((6,7, 2,6,1))]
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores)
>>> print(x.stack_shape)
(6, 7)
Return type:

Tuple[int, Ellipsis]

property shape: Tuple[int, Ellipsis]#

Shape of the represented dense tensor. shape=(N0,...,N(d-1))

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = (np.zeros((4,14)), np.zeros((5,15)), np.zeros((6,16)))
>>> tt_cores = (np.zeros((1,4,3)), np.zeros((3,5,2)), np.zeros((2,6,1)))
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores)
>>> print(x.shape)
(14, 15, 16)
Return type:

Tuple[int, Ellipsis]

property tucker_ranks: Tuple[int, Ellipsis]#

Tucker ranks. tucker_ranks=(n0,...,n(d-1))

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = (np.zeros((4,14)), np.zeros((5,15)), np.zeros((6,16)))
>>> tt_cores = (np.zeros((1,4,3)), np.zeros((3,5,2)), np.zeros((2,6,1)))
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores)
>>> print(x.tucker_ranks)
(4, 5, 6)
Return type:

Tuple[int, Ellipsis]

property tt_ranks: Tuple[int, Ellipsis]#

TT ranks. tt_ranks=(r0,...,rd)

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = (np.zeros((4,14)), np.zeros((5,15)), np.zeros((6,16)))
>>> tt_cores = (np.zeros((1,4,3)), np.zeros((3,5,2)), np.zeros((2,6,1)))
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores)
>>> print(x.tt_ranks)
(1, 3, 2, 1)
Return type:

Tuple[int, Ellipsis]

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

Tuple containing Tucker ranks and TT ranks.

  • ranks           = (tucker_ranks, tt_ranks)

  • tucker_ranks    = (n0,...,n(d-1))

  • tt_ranks        = (r0,...,rd)

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = (np.zeros((4,14)), np.zeros((5,15)), np.zeros((6,16)))
>>> tt_cores = (np.zeros((1,4,3)), np.zeros((3,5,2)), np.zeros((2,6,1)))
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores)
>>> print(x.ranks)
((4, 5, 6), (1, 3, 2, 1))
Return type:

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

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

Tuple containing tensor shape, Tucker ranks, TT ranks, and stack shape.

  • structure = (shape, tucker_ranks, tt_ranks, stack_shape)

  • shape           = (N0,...,N(d-1))

  • tucker_ranks    = (n0,...,n(d-1))

  • tt_ranks        = (r0,...,rd)

  • stack_shape (optional, default: stack_shape=())

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = (np.zeros((4,14)), np.zeros((5,15)), np.zeros((6,16)))
>>> tt_cores = (np.zeros((1,4,3)), np.zeros((3,5,2)), np.zeros((2,6,1)))
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores)
>>> print(x.structure)
((14, 15, 16), (4, 5, 6), (1, 3, 2, 1), ())
Return type:

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

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

Shapes of the Tucker and TT cores.

  • cores_shapes            = (tucker_core_shapes, tt_core_shapes).

  • len(tucker_core_shapes) = len(tt_core_shapes) = d

  • tucker_core_shapes[ii]  = (ni, Ni)

  • tt_core_shapes[ii]      = (ri, ni, r(i+1))

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = (np.zeros((4,14)), np.zeros((5,15)), np.zeros((6,16)))
>>> tt_cores = (np.zeros((1,4,3)), np.zeros((3,5,2)), np.zeros((2,6,1)))
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores) # TuckerTensorTrain, cores filled with zeros
>>> print(x.core_shapes)
(((4, 14), (5, 15), (6, 16)), ((1, 4, 3), (3, 5, 2), (2, 6, 1)))
Return type:

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

property size: int#

Size of the dense tensor represented by this TuckerTensorTrain. size=N0*...*N(d-1).

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = (np.zeros((4,14)), np.zeros((5,15)), np.zeros((6,16)))
>>> tt_cores = (np.zeros((1,4,3)), np.zeros((3,5,2)), np.zeros((2,6,1)))
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores) # TuckerTensorTrain, cores filled with zeros
>>> print(x.size == 14*15*16)
True
Return type:

int

property data_size: int#

Sum of the sizes of all Tucker and TT cores.

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> tucker_cores = (np.zeros((4,14)), np.zeros((5,15)), np.zeros((6,16)))
>>> tt_cores = (np.zeros((1,4,3)), np.zeros((3,5,2)), np.zeros((2,6,1)))
>>> x = t3.TuckerTensorTrain(tucker_cores, tt_cores) # TuckerTensorTrain, cores filled with zeros
>>> print(x.data_size == 4*14 + 5*15 + 6*16 + 1*4*3 + 3*5*2 + 2*6*1)
True
Return type:

int

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

Ranks of the smallest possible TuckerTensorTrain that could represent the same dense tensor as this TuckerTensorTrain. TuckerTensorTrains ranks may be made minimal using T3-SVD.

  • minimal_ranks = (minimal_tucker_ranks, minimal_tt_ranks)

  • len(minimal_tucker_ranks) = d

  • len(minimal_tt_ranks) = d+1

Examples

A Tucker rank is not minimal:

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> x = t3.TuckerTensorTrain.randn((13,14,15,16), (4,99,6,7), (1,4,9,7,1))
>>> print(x.ranks)
((4, 99, 6, 7), (1, 4, 9, 7, 1))
>>> print(x.minimal_ranks)
((4, 14, 6, 7), (1, 4, 9, 7, 1))

A TT-rank is not minimal:

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> x = t3.TuckerTensorTrain.randn((13,14,15,16), (4,5,6,7), (1,4,99,7,1))
>>> print(x.ranks)
((4, 5, 6, 7), (1, 4, 99, 7, 1))
>>> print(x.minimal_ranks)
((4, 5, 6, 7), (1, 4, 20, 7, 1))
Return type:

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

property has_minimal_ranks: bool#

True if this Tucker tensor train’s ranks are minimal, False otherwise.

Examples

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> x = t3.TuckerTensorTrain.randn((13,14,15,16), (4,99,6,7), (1,4,9,7,1))
>>> print(x.has_minimal_ranks) # Tucker rank too big
False
>>> x = t3.TuckerTensorTrain.randn((13,14,15,16), (4,5,6,7), (1,99,9,7,1))
>>> print(x.has_minimal_ranks) # TT rank too big
False
>>> x = t3.TuckerTensorTrain.randn((13,14,15,16), (4,5,6,7), (1,4,9,7,1))
>>> print(x.has_minimal_ranks)
True

Make ranks minimal with t3svd:

>>> import numpy as np
>>> import t3toolbox.tucker_tensor_train as t3
>>> x = t3.TuckerTensorTrain.randn((13,14,15,16), (4,5,6,7), (1,99,9,7,1))
>>> print(x.has_minimal_ranks)
False
>>> print(x.minimal_ranks)
((4, 5, 6, 7), (1, 4, 9, 7, 1))
>>> x2 = x.t3svd()[0]
>>> print(x2.has_minimal_ranks)
True
Return type:

bool

property contains_jax: bool#

True if any Tucker or TT cores are jax arrays, False if all Tucker and TT cores are numpy arrays.

See Also:#

TuckerTensorTrain.to_jax() TuckerTensorTrain.to_numpy()

Return type:

bool

Methods#

__repr__()

get_core_shapes(shape, tucker_ranks, tt_ranks[, ...])

Compute the Tucker and TT core shapes for a Tucker tensor train.

get_minimal_ranks(shape, tucker_ranks, tt_ranks)

Find minimal ranks for a hypothetical TuckerTensorTrain with given shape and ranks.

has_numerically_minimal_ranks([rtol])

True if the ranks are numerically minimal: no stored rank is numerically redundant.

is_left_orthogonal([atol])

True (per stack element) if this T3 is in left-orthogonal form: every Tucker core

is_right_orthogonal([atol])

True (per stack element) if this T3 is in right-orthogonal form: every Tucker core

validate()

Check internal consistency of the Tucker tensor train.

__post_init__()

to_dense([squash_tails])

Form dense tensor from this TuckerTensorTrain.

segment(start, stop)

Extract contiguous segment of this TuckerTensorTrain. Segments must have length at least one.

concatenate(xx)

Concatenates TuckerTensorTrain segments.

squash_tails()

Make leading and trailing TT ranks equal to 1 (r0=rd=1), without changing represented dense tensor.

reverse()

Reverse Tucker tensor train.

resize(new_shape, new_tucker_ranks, new_tt_ranks)

Change shape and ranks by resizing cores. Makes cores bigger via zero padding. Makes cores smaller via truncation.

to_jax()

Convert core arrays defining TuckerTensorTrain to Jax arrays.

to_numpy()

Convert arrays defining TuckerTensorTrain into Numpy arrays.

copy()

Copy TuckerTensorTrain.

unstack()

If this object contains multiple stacked T3s, this unstacks them

stack(xx)

Stacks an array-like tree of TuckerTensorTrains into one stacked TuckerTensorTrain.

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

Construct a Tucker tensor train of zeros.

ones(shape[, stack_shape, use_jax])

Construct TuckerTensorTrain representation of dense tensor filled with ones.

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

Construct a Tucker tensor train with random cores. Core entries are i.i.d. draws from N(0,1).

from_canonical(factors)

Constructs TuckerTensorTrain from Canonical decomposition.

from_tensor_train(tt_cores)

Convert tensor train into Tucker tensor train by using identity matrices for Tucker bases.

to_tensor_train()

Convert this TuckerTensorTrain to a tensor train by contracting Tucker bases with TT cores.

to_vector()

Converts a TuckerTensorTrain into a 1D vector containing the core entries.

from_vector(x_flat, shape, tucker_ranks, tt_ranks[, ...])

Constructs a TuckerTensorTrain from a 1D vector containing the core entries.

save(file)

Save a Tucker tensor train to a file.

load(file[, use_jax])

Load a Tucker tensor train from a file.

__add__(other)

Add this TuckerTensorTrains self to other tensor, yielding a tensor result = self + other with summed ranks.

__mul__(other[, use_jax])

Elementwise multiplication of a Tucker tensor train by another tensor, result = self * other.

t3m(other[, method, max_tucker_ranks, max_tt_ranks, ...])

Elementwise (Hadamard) product self ⊙ other with optional rank truncation.

__neg__()

Scale a TuckerTensorTrain by -1. result=-self.

__sub__(other)

Subtract Tucker tensor trains, result = self - other, yielding a Tucker tensor train with summed ranks.

inner(other[, use_orthogonalization])

Compute Hilbert-Schmidt inner product of this TuckerTensorTrain with other tensor, result=(self, other)_HS.

norm([use_orthogonalization])

Compute Hilbert-Schmidt (Frobenius) norm of this TuckerTensorTrain.

sum([axis])

Sum over one or more axes of TuckerTensorTrain.

sum_stack([axis])

Sum the tensors represented by a stacked TuckerTensorTrain over one or more stack axes.

sum_stack_corewise([axis])

Sum the core arrays of a stacked TuckerTensorTrain over one or more stack axes.

down_svd_tucker_core(ii[, min_rank, max_rank, rtol, atol])

Compute SVD of ith tucker core and contract non-orthogonal factor into the TT-core above.

left_svd_tt_core(ii[, min_rank, max_rank, rtol, atol])

Compute SVD of ith TT-core left unfolding and contract non-orthogonal factor into the TT-core to the right.

right_svd_tt_core(ii[, min_rank, max_rank, rtol, atol])

Compute SVD of ith TT-core right unfolding and contract non-orthogonal factor into the TT-core to the left.

up_svd_tt_core(ii[, min_rank, max_rank, rtol, atol])

Compute SVD of ith TT-core right unfolding and contract non-orthogonal factor down into the tucker core below.

orthogonalize_relative_to_tucker_core(ii)

Orthogonalize cores in the TuckerTensorTrain relative to the ith Tucker core.

orthogonalize_relative_to_tt_core(ii)

Orthogonalize cores in the TuckerTensorTrain relative to the ith TT-core.

down_orthogonalize_tucker_cores()

Orthogonalize Tucker cores downwards, pushing remainders onto TT cores above.

up_orthogonalize_tt_cores()

Up orthogonalize TT cores, pushing remainders onto Tucker cores below.

left_orthogonalize_tt_cores([return_variation_cores])

Left orthogonalize the TT cores, possibly returning variation cores as well.

right_orthogonalize_tt_cores([return_variation_cores])

Right orthogonalize the TT cores, possibly returning variation cores as well.

entries(index)

Compute an entry (or multiple entries) of a Tucker tensor train.

apply(vecs)

Contract a Tucker tensor train with vectors in all indices.

probe(ww)

Probe a TuckerTensorTrain.

probe_ambient_transpose(ztildes, ww[, sum_over_probes])

Ambient transpose of probe(): back-project probe residuals into canonical (CP) factors.

probe_corewise_transpose(ztildes, ww[, sum_over_probes])

Corewise (non-manifold) transpose of probe(): gradient w.r.t. this tensor's cores.

apply_ambient_transpose(c, ww[, sum_over_probes])

Ambient transpose of apply(): back-project c into canonical (CP) factors.

entries_ambient_transpose(c, index, shape[, ...])

Ambient transpose of entries(): scatter c at index into canonical (CP) factors.

apply_corewise_transpose(c, ww[, sum_over_probes])

Corewise (non-manifold) transpose of apply(): gradient w.r.t. this tensor's cores.

entries_corewise_transpose(c, index[, sum_over_probes])

Corewise (non-manifold) transpose of entries(): gradient w.r.t. this tensor's cores.

probe_derivatives(ww, pp, order)

Symmetric directional derivatives of probing this Tucker tensor train, in one repeated direction.

apply_derivatives(ww, pp, order)

Symmetric directional derivatives of applying this T3 in all modes, in one repeated direction.

entries_derivatives(index, pp, order)

Symmetric directional derivatives of this T3's entries at index, in direction P.

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

Corewise (non-manifold) transpose of probe_derivatives(): the core-space gradient.

apply_corewise_derivatives_transpose(c, ww, pp, order)

Corewise transpose of apply_derivatives(): gradient of the apply-derivative jets

entries_corewise_derivatives_transpose(c, index, pp, order)

Corewise transpose of entries_derivatives(): gradient of the entry-derivative jets

t3svd([max_tt_ranks, max_tucker_ranks, rtol, atol, ...])

Compute (truncated) T3-SVD of Tucker tensor train.

continuation_ranks([tau, n_chunk, kappa_guard, ...])

Rank-continuation update (Section 5.4.1): the ranks to grow to next, from this iterate's spectra.

rank_adjustment_sweep([direction])

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

t3svd_dense(T[, stack_shape, max_tucker_ranks, ...])

Compute TuckerTensorTrain representation or approximation of a dense tensor.