t3toolbox.basis_coordinates_format.T3Basis ========================================== .. py: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. .. seealso:: :py:obj:`T3Coordinates`, :py:obj:`check_t3_base`, :py:obj:`orthogonal_representations`, :py:obj:`oblique_gauge_projection` .. rubric:: 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))) .. py:attribute:: up_tucker_cores :type: t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis] .. py:attribute:: left_tt_cores :type: t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis] .. py:attribute:: right_tt_cores :type: t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis] .. py:attribute:: down_tt_cores :type: t3toolbox.backend.common.typ.Tuple[t3toolbox.backend.common.NDArray, Ellipsis] .. py:method:: d() -> int .. py:method:: shape() -> t3toolbox.backend.common.typ.Tuple[int, Ellipsis] .. py:method:: up_ranks() -> t3toolbox.backend.common.typ.Tuple[int, Ellipsis] .. py:method:: down_ranks() -> t3toolbox.backend.common.typ.Tuple[int, Ellipsis] .. py:method:: left_ranks() -> t3toolbox.backend.common.typ.Tuple[int, Ellipsis] .. py:method:: right_ranks() -> t3toolbox.backend.common.typ.Tuple[int, Ellipsis] .. py:method:: stack_shape() -> t3toolbox.backend.common.typ.Tuple[int, Ellipsis] .. py:method:: 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]] .. py:method:: 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 | | | | .. rubric:: 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))) .. py:method:: 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]] .. py:method:: validate() -> None Check rank and shape consistency of Tucker tensor train basis (`T3Basis`). :param x: :type x: T3Basis :raises ValueError: Error raised if the cores of the T3Basis have inconsistent shapes. .. seealso:: :py:obj:`T3Basis`, :py:obj:`T3Coordinates` .. py:method:: __post_init__()