ManifoldGeometry
================

.. toctree::
   :hidden:

   /autoapi/t3toolbox/manifold/ManifoldGeometry.frame
   /autoapi/t3toolbox/manifold/ManifoldGeometry.randn
   /autoapi/t3toolbox/manifold/ManifoldGeometry.random_orthogonal
   /autoapi/t3toolbox/manifold/ManifoldGeometry.randn_like
   /autoapi/t3toolbox/manifold/ManifoldGeometry.project
   /autoapi/t3toolbox/manifold/ManifoldGeometry.project_oblique
   /autoapi/t3toolbox/manifold/ManifoldGeometry.inner
   /autoapi/t3toolbox/manifold/ManifoldGeometry.norm
   /autoapi/t3toolbox/manifold/ManifoldGeometry.retract
   /autoapi/t3toolbox/manifold/ManifoldGeometry.project_ambient
   /autoapi/t3toolbox/manifold/ManifoldGeometry.transport

.. py:class:: t3toolbox.manifold.ManifoldGeometry

   The Riemannian geometry of the fixed-rank Tucker tensor train manifold ``M``.

   Optimization happens *on* ``M``: tangents live in ``T_xM`` with an orthonormal, gauged frame, the
   metric is Hilbert-Schmidt, and one moves by the manifold retraction (truncate the shifted
   doubled-rank embedding back to the frame ranks). A geometry is a *stateless* bundle of the three
   chart-level choices that distinguish this from the over-parametrized corewise geometry -- the
   frame (:py:meth:`frame`), the gauge projection ``Pi`` (:py:meth:`project`), and the retraction
   (:py:meth:`retract`) -- plus the manifold-only ambient projection and transport. The point lives
   in the caller (or the fitting model), not the geometry; use the module singleton :py:data:`MANIFOLD`.

   See Section 6 and Appendix A.3 of Alger et al. (2026), "Tucker Tensor Train Taylor Series"
   (arXiv:2603.21141). The corewise counterpart is :py:class:`CorewiseGeometry`.

   .. rubric:: Examples

   >>> import numpy as np
   >>> import t3toolbox.tucker_tensor_train as t3
   >>> import t3toolbox.manifold as t3m
   >>> np.random.seed(0)
   >>> x = t3.TuckerTensorTrain.randn((10, 11, 12), (3, 4, 3), (1, 2, 2, 1))
   >>> frame = t3m.MANIFOLD.frame(x)            # orthonormal frame at x
   >>> print(frame.is_orthogonal())
   True
   >>> v = t3m.MANIFOLD.randn(frame)           # a standard Gaussian on T_xM (gauged)
   >>> print(v.is_gauged())
   True
   >>> y = t3m.MANIFOLD.retract(t3m.T3Tangent.zeros(frame))   # retract the zero tangent == the base point
   >>> print(bool(np.allclose(y.to_dense(), x.to_dense())))
   True

Methods
-------

.. autoapisummary::

   t3toolbox.manifold.ManifoldGeometry.frame
   t3toolbox.manifold.ManifoldGeometry.randn
   t3toolbox.manifold.ManifoldGeometry.random_orthogonal
   t3toolbox.manifold.ManifoldGeometry.randn_like
   t3toolbox.manifold.ManifoldGeometry.project
   t3toolbox.manifold.ManifoldGeometry.project_oblique
   t3toolbox.manifold.ManifoldGeometry.inner
   t3toolbox.manifold.ManifoldGeometry.norm
   t3toolbox.manifold.ManifoldGeometry.retract
   t3toolbox.manifold.ManifoldGeometry.project_ambient
   t3toolbox.manifold.ManifoldGeometry.transport