CorewiseGeometry
================

.. toctree::
   :hidden:

   /autoapi/t3toolbox/manifold/CorewiseGeometry.frame
   /autoapi/t3toolbox/manifold/CorewiseGeometry.randn
   /autoapi/t3toolbox/manifold/CorewiseGeometry.randn_like
   /autoapi/t3toolbox/manifold/CorewiseGeometry.project
   /autoapi/t3toolbox/manifold/CorewiseGeometry.inner
   /autoapi/t3toolbox/manifold/CorewiseGeometry.norm
   /autoapi/t3toolbox/manifold/CorewiseGeometry.retract

.. py:class:: t3toolbox.manifold.CorewiseGeometry

   The Euclidean geometry of the core parameter space ``P`` (the over-parametrized cover of ``M``).

   Optimization happens *on* the raw cores: tangents are perturbations of the cores ``(U, G, G, G)``
   (the non-orthonormal frame whose down/left/right cores are all the TT cores ``G``), the metric is
   the plain Euclidean (corewise) inner product, the "projection" is the identity (no gauge), and the
   retraction is vector addition in the cores. The corewise gradient is a genuine
   :py:class:`T3Tangent` at this frame -- not a raw tuple. Gauge directions lie in the kernel of the
   pushforward, so the Gauss-Newton Hessian is gauge-singular (fine for Adam / L-BFGS, needs
   regularization for Newton). Use the module singleton :py:data:`COREWISE`. The §6.3 substitution
   ``(O, P, Q) -> G`` is exactly this change of frame; the manifold counterpart is
   :py:class:`ManifoldGeometry`.

   .. 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.COREWISE.frame(x)            # the (U, G, G, G) frame
   >>> v = t3m.COREWISE.randn(frame)           # raw randn cores (no gauge)
   >>> print(v.is_gauged())
   False
   >>> y = t3m.COREWISE.retract(v)            # additive: cores += v (a multilinear curve on M)
   >>> U, G = x.data
   >>> dU, dG = v.variations.tucker_variations, v.variations.tt_variations
   >>> ref = t3.TuckerTensorTrain(tuple(u + du for u, du in zip(U, dU)),
   ...                            tuple(g + dg for g, dg in zip(G, dG)))
   >>> print(bool(np.allclose(y.to_dense(), ref.to_dense())))
   True

Methods
-------

.. autoapisummary::

   t3toolbox.manifold.CorewiseGeometry.frame
   t3toolbox.manifold.CorewiseGeometry.randn
   t3toolbox.manifold.CorewiseGeometry.randn_like
   t3toolbox.manifold.CorewiseGeometry.project
   t3toolbox.manifold.CorewiseGeometry.inner
   t3toolbox.manifold.CorewiseGeometry.norm
   t3toolbox.manifold.CorewiseGeometry.retract