ManifoldGeometry.project_ambient
================================

.. py:method:: t3toolbox.manifold.ManifoldGeometry.project_ambient(frame, grad, method = 'contraction')

   .. code-block:: python

      def project_ambient(
              self,
              frame:  bvf.T3Frame,                               # orthogonal base point of the tangent space
              grad:   typ.Union[t3.TuckerTensorTrain, NDArray],  # ambient gradient: a T3 or a dense array
              method: str = 'contraction',                       # dense only: 'contraction' (no SVD) or 't3svd'
      ) -> T3Tangent:  # the Riemannian gradient (gauged projection of grad) at frame


   Project an ambient gradient onto ``T_xM`` -- the Riemannian gradient.

   ``grad`` is the Euclidean/ambient gradient, either a :py:class:`TuckerTensorTrain` or a dense
   array (leading axes beyond the ``d`` modes are a stack). Returns the (gauged) tangent
   ``P_T(grad)``; the residual ``grad - P_T(grad)`` is orthogonal to the tangent space. Requires
   an **orthogonal** ``frame`` (minimal rank is *not* required). For a dense ``grad``, ``method``
   selects the algorithm (same projection): ``'contraction'`` (default, contract against the
   frames, no SVD) or ``'t3svd'`` (exact T3-SVD then project; expensive). This is the
   tangent-space projection of Section 6 / Appendix A.3. **Safe mode** enforces the orthogonal
   requirement (raises otherwise); skipped under ``safety.unsafe()`` / a jax trace.