t3toolbox.manifold.tangent_to_t3
================================

.. py:function:: t3toolbox.manifold.tangent_to_t3(variation: t3toolbox.basis_coordinates_format.T3Variation, base: t3toolbox.basis_coordinates_format.T3Base, include_shift: bool = False, use_jax: bool = False) -> t3toolbox.tucker_tensor_train.TuckerTensorTrain

   Rank 2r Tucker tensor train representation of tangent vector.

   Without shift, we use the formula::

       v(x,y,z,w) = ([dU1(B x) L1(B x)]) ([R2(B y)        0]) ([R3(B z)        0]) ([R4(B w) ])
                    (                  ) ([dU2(B y) L2(B y)]) ([dU3(B z) L3(B z)]) ([dU4(B w)])
                    (         +        ) (         +        ) (        +         ) (    +     )
                    ([O1(dB x)       0]) ([0              0]) ([0              0]) ([0       ])
                    (                  ) ([O2(dB y)       0]) ([O3(dB z)       0]) ([O4(dB w)])

   With shift is same as unshifted, except last backend modified as follows::

       [R4(B w) ]                  [R4(B w)           ]
       [dU4(B w)]                  [L4(B w) + dU4(B w)]
           +             ->            +
       [0       ]                  [0                 ]
       [O4(dB w)]                  [O4(dB w)          ]

   :param variation: Variation representing the tangent vector
   :type variation: T3Variation,
   :param base: Representation of the base point at which the tangent space attaches to the manifold.
   :type base: T3Base,
   :param include_shift: If False, return tangent vector v only. If True, shift tangent vector so it is attached at the base point, p+v.
   :type include_shift: bool
   :param xnp: Linear algebra backend. Default: np (numpy)

   :returns: Tucker tensor train representation of tangent vector, which has doubled ranks
   :rtype: TuckerTensorTrain

   .. seealso:: :py:obj:`T3Base`, :py:obj:`T3Variation`, :py:obj:`TuckerTensorTrain`

   .. rubric:: Examples

   >>> import numpy as np
   >>> import t3toolbox.tucker_tensor_train as t3
   >>> import t3toolbox.manifold as t3m
   >>> import t3toolbox.orthogonalization as orth
   >>> p = t3.t3_corewise_randn(((14,15,16), (4,5,6), (2,3,2,2)))
   >>> base, _ = orth.orthogonal_representations(p)
   >>> variation = t3m.tangent_randn(base)
   >>> v_t3 = t3m.tangent_to_t3(variation, base) # tangent vector only (attached at zero)
   >>> v_dense = t3.t3_to_dense(v_t3)
   >>> v_dense2 = t3m.tangent_to_dense(variation, base)
   >>> print(np.linalg.norm(v_dense - v_dense2))
   2.678565538404836e-15
   >>> p_plus_v_t3 = t3m.tangent_to_t3(variation, base, include_shift=True) # shifted tangent vector (include attachment at base point)
   >>> p_plus_v_dense = t3.t3_to_dense(p_plus_v_t3)
   >>> p_plus_v_dense2 = v_dense2 + t3.t3_to_dense(p)
   >>> print(np.linalg.norm(p_plus_v_dense - p_plus_v_dense2))
   1.2102169224182523e-12