t3toolbox.manifold.project_t3_onto_tangent_space
================================================

.. py:function:: t3toolbox.manifold.project_t3_onto_tangent_space(x: Union[t3toolbox.tucker_tensor_train.TuckerTensorTrain, t3toolbox.OLD_uniform.UniformTuckerTensorTrain], orthogonal_base: Union[t3toolbox.basis_coordinates_format.T3Base, t3toolbox.OLD_uniform.UniformT3Base], use_jax: bool = False) -> t3toolbox.basis_coordinates_format.T3Variation

   Projects TuckerTensorTrain onto tangent space to the manifold of fixed rank TuckerTensorTrains.

   :param x: TuckerTensorTrain to project
   :type x: t3.TuckerTensorTrain
   :param orthogonal_base: Minimal rank orthogonal representations of base point on manifold where tangent space is attached
   :type orthogonal_base: T3Base
   :param xnp: Linear algebra backend. Default: np (numpy)

   :returns: Gauged variation representing the orthogonal projection of x onto the tangent space.
   :rtype: T3Variation

   .. seealso:: :py:obj:`T3Base`, :py:obj:`oblique_gauge_projection`, :py:obj:`orthogonal_gauge_projection`, :py:obj:`ADD`

   .. 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), (5,3,2,4)))
   >>> base, _ = orth.orthogonal_representations(p)
   >>> x = t3.t3_corewise_randn(((14,15,16), (7,4,8), (3,5,4,2)))
   >>> proj_x = t3m.project_t3_onto_tangent_space(x, base) # Project x onto tangent space
   >>> P = t3.t3_to_dense(p)
   >>> X = t3.t3_to_dense(x)
   >>> proj_X = t3m.tangent_to_dense(proj_x, base)
   >>> print(np.sum((X - proj_X) * (proj_X - P)) / np.sum(X)) # Check that x was projected orthogonally
   -2.7295025395842007e-13

   Uniform example: DOESNT WORK YET

   >>> import numpy as np
   >>> import t3toolbox.tucker_tensor_train as t3
   >>> import t3toolbox.manifold as t3m
   >>> import t3toolbox.uniform as ut3
   >>> import t3toolbox.uniform_manifold as utm
   >>> import t3toolbox.orthogonalization as orth
   >>> import t3toolbox.t3svd as t3svd
   >>> p = t3.t3_corewise_randn(((14,15,16), (4,5,6), (5,3,2,4)))
   # >>> p = t3.t3_corewise_randn(((15,15,15), (5,5,5), (1,3,3,1)))
   >>> p, _, _ = t3svd.t3svd(p)
   >>> base, dummy_var = orth.orthogonal_representations(p)
   >>> x = t3.t3_corewise_randn(((14,15,16), (7,4,8), (3,5,4,2)))
   # >>> x = t3.t3_corewise_randn(((15,15,15), (5,5,5), (1,3,3,1)))
   >>> x, _, _ = t3svd.t3svd(x)
   >>> proj_x = t3m.project_t3_onto_tangent_space(x, base) # Project x onto tangent space
   >>> dense_proj_x = t3m.tangent_to_dense(proj_x, base)
   >>> _, uniform_base, bv_mask = ut3.bv_to_ubv(dummy_var, base)
   >>> uniform_x, x_mask = ut3.t3_to_ut3(x)
   >>> uniform_proj_x = t3m.project_t3_onto_tangent_space(uniform_x, uniform_base) # Project x onto tangent space
   >>> dense_uniform_proj_x = utm.uniform_tangent_to_dense(uniform_proj_x, uniform_base, bv_mask)
   >>> print(np.linalg.norm(dense_uniform_proj_x - dense_proj_x))