t3toolbox.basis_coordinates_format.T3Basis#

class t3toolbox.basis_coordinates_format.T3Basis#

Basis for basis-coordinates representation of TuckerTensorTrains

Often, one works with TuckerTensorTrains of the following forms:

1--(H0)--R1---R2---1    1---L0--(H1)--R2---1    1---L0---L1--(H2)--1
    |    |    |             |    |    |             |    |    |
    U0   U1   U2            U0   U1   U2            U0   U1   U2
    |    |    |             |    |    |             |    |    |

1---O0---R1---R2---1    1---L0---O1---R2---1    1---L0---L1---O2---1
    |    |    |             |    |    |             |    |    |
   (V0)  U1   U2            U0  (V1)  U2            U0   U1  (V2)
    |    |    |             |    |    |             |    |    |

In each of these, there is a special “coordinate” core, indicated by parentheses (X), surrounded by “basis” cores.

The components of T3Basis are the “basis cores”:

up_tucker_cores = (U0, …, U(d-1)), elm_shape=(nUi, Ni)
left_tt_cores = (L0, …, L(d-1)), elm_shape=(rLi, ni, rL(i+1))
right_tt_cores = (R0, …, R(d-1)), elm_shape=(rRi, ni, rR(i+1))
outer_tt_cores = (O0, …, O(d-1)), elm_shape=(rLi, nDi, rR(i+1))

The components of T3Coordinates are the “variation cores”:

tucker_variations = (V0, …, V(d-1)), elm_shape=(nDi, Ni)
tt_variations = (H0, …, H(d-1)), elm_shape=(rLi, nUi, rRi)

Note that Ld and R0 are not used in these diagrams.

The edge ranks are shown in the following diagrams:

   rL0       rL1       rR2      rR(d-1)         rRd
1 ------ L0 ----- (H1) ----- ... ------ R(d-1) ------ 1
         |         |                    |
         | nU0     | nU1                | nU(d-1)
         |         |                    |
         U0        U1                   Ud
         |         |                    |
         | N0      | N1                 | N(d-1)
         |         |                    |

and:

   rL0       rL1       rR2      rR(d-1)         rRd
1 ------ L0 ------ O1 ------ ... ------ R(d-1) ------ 1
         |         |                    |
         | nU0     | nO1                | nU(d-1)
         |         |                    |
         U0       (V1)                   Ud
         |         |                    |
         | N0      | N1                 | N(d-1)
         |         |                    |

A tangent vector can be written as the sum of all the tensor diagrams above. In this case, the basis cores are representations of the point where the tangent space attaches to the manifold, and the coordinate cores define the tangent vector with respect to the basis.

Often, it is desirable for the base cores to be orthogonal as follows:

up_tucker_cores = (U0,…,U(d-1)), orthogonal: U_ia U_ja = delta_ij
left_tt_cores = (L0,…,L(d-1)), left-orthogonal: L_abi L_abj = delta_ij
right_tt_cores = (R0,…,R(d-1)), right-orthogonal R_ibc R_jbc = delta_ij
outer_tt_cores = (O0,…,O(d-1)), outer-orthogonal O_aib O_ajb = delta_ij

Often, it is desirable for the variations to satisfy the following Gauge conditions:

U_ia V_ja = 0 (all V)
L_abi H_abj = 0 (all but the last H)

If these conditions are satisfied, then one can do “dumb” corewise linear algebra backend (add, scale, dot product, etc) with the variations, and those backend faithfully correspond to linear algebra backend with the N1 x … x Nd tangent vectors represented by the variations.

See also

T3Coordinates, check_t3_base, orthogonal_representations, oblique_gauge_projection

Examples

>>> import numpy as np
>>> import t3toolbox.basis_coordinates_format as bcf
>>> ss = (2,3)
>>> tucker_cores = (np.ones(ss+(10, 14)), np.ones(ss+(11, 15)), np.ones(ss+(12, 16)))
>>> left_tt_cores = (np.ones(ss+(1, 10, 2)), np.ones(ss+(2, 11, 3)), np.ones(ss+(3,12,5)))
>>> right_tt_cores = (np.ones(ss+(2, 10, 4)), np.ones(ss+(4, 11, 5)), np.ones(ss+(5, 12, 1)))
>>> outer_tt_cores = (np.ones(ss+(1, 9, 4)), np.ones(ss+(2, 8, 5)), np.ones(ss+(3, 7, 1)))
>>> basis = bcf.T3Basis(tucker_cores, left_tt_cores, right_tt_cores, outer_tt_cores)
>>> print(basis.structure)
((14, 15, 16), (10, 11, 12), (1, 2, 3, 5), (2, 4, 5, 1), (9, 8, 7), (2, 3))
>>> print(basis.coordinate_shapes)
(((9, 14), (8, 15), (7, 16)), ((1, 10, 4), (2, 11, 5), (3, 12, 1)))

up_tucker_cores: t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis]#

left_tt_cores: t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis]#

right_tt_cores: t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis]#

down_tt_cores: t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis]#

d() → int#

shape() → t3toolbox.backend.common.typ.Tuple[int, Ellipsis]#

up_ranks() → t3toolbox.backend.common.typ.Tuple[int, Ellipsis]#

down_ranks() → t3toolbox.backend.common.typ.Tuple[int, Ellipsis]#

left_ranks() → t3toolbox.backend.common.typ.Tuple[int, Ellipsis]#

right_ranks() → t3toolbox.backend.common.typ.Tuple[int, Ellipsis]#

stack_shape() → t3toolbox.backend.common.typ.Tuple[int, Ellipsis]#

structure() → t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.typ.Tuple[int, Ellipsis], t3toolbox.backend.common.typ.Tuple[int, Ellipsis], t3toolbox.backend.common.typ.Tuple[int, Ellipsis], t3toolbox.backend.common.typ.Tuple[int, Ellipsis], t3toolbox.backend.common.typ.Tuple[int, Ellipsis], t3toolbox.backend.common.typ.Tuple[int, Ellipsis]]#

coordinate_shapes() → t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.typ.Tuple[int, Ellipsis], Ellipsis], t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.typ.Tuple[int, Ellipsis], Ellipsis]]#

T3Coordinates shapes that fit with this T3Basis.

Shapes of the “holes” in the following tensor diagrams:

1 -- L0 -- ( ) -- R2 -- R3 -- 1
     |      |      |      |
     U0     U1     U2     U3
     |      |      |      |

1 -- L0 -- L1 -- O2 -- R3 -- 1
     |     |     |     |
     U0    U1    ( )   U3
     |     |     |     |

Examples

>>> import numpy as np
>>> import t3toolbox.basis_coordinates_format as bcf
>>> ss = (2,3) # not included in coordinate_shapes.
>>> tucker_cores = (np.ones(ss+(10, 14)), np.ones(ss+(11, 15)), np.ones(ss+(12, 16)))
>>> left_tt_cores = (np.ones(ss+(1, 10, 2)), np.ones(ss+(2, 11, 3)), np.ones(ss+(3,12,5)))
>>> right_tt_cores = (np.ones(ss+(2, 10, 4)), np.ones(ss+(4, 11, 5)), np.ones(ss+(5, 12, 1)))
>>> outer_tt_cores = (np.ones(ss+(1, 9, 4)), np.ones(ss+(2, 8, 5)), np.ones(ss+(3, 7, 1)))
>>> basis = bcf.T3Basis(tucker_cores, left_tt_cores, right_tt_cores, outer_tt_cores)
>>> print(basis.coordinate_shapes)
(((9, 14), (8, 15), (7, 16)), ((1, 10, 4), (2, 11, 5), (3, 12, 1)))

data() → t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis], t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis], t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis], t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis]]#

validate() → None#

Check rank and shape consistency of Tucker tensor train basis (T3Basis).

Parameters:: x (T3Basis)
Raises:: ValueError – Error raised if the cores of the T3Basis have inconsistent shapes.