SharedGeometry
==============

.. toctree::
   :hidden:

   /autoapi/t3toolbox/shared_geometry/SharedGeometry.__eq__
   /autoapi/t3toolbox/shared_geometry/SharedGeometry.__hash__
   /autoapi/t3toolbox/shared_geometry/SharedGeometry.__repr__
   /autoapi/t3toolbox/shared_geometry/SharedGeometry.groups
   /autoapi/t3toolbox/shared_geometry/SharedGeometry.frame
   /autoapi/t3toolbox/shared_geometry/SharedGeometry.shared_frame_data
   /autoapi/t3toolbox/shared_geometry/SharedGeometry.precompute
   /autoapi/t3toolbox/shared_geometry/SharedGeometry.project
   /autoapi/t3toolbox/shared_geometry/SharedGeometry.project_oblique
   /autoapi/t3toolbox/shared_geometry/SharedGeometry.inner
   /autoapi/t3toolbox/shared_geometry/SharedGeometry.norm
   /autoapi/t3toolbox/shared_geometry/SharedGeometry.randn
   /autoapi/t3toolbox/shared_geometry/SharedGeometry.randn_like
   /autoapi/t3toolbox/shared_geometry/SharedGeometry.retract
   /autoapi/t3toolbox/shared_geometry/SharedGeometry.project_ambient
   /autoapi/t3toolbox/shared_geometry/SharedGeometry.transport

.. py:class:: t3toolbox.shared_geometry.SharedGeometry(base, sharing)

   The shared (SF-T3) geometry: a base geometry restricted to tied Tucker factors.

   Construct via :py:func:`shared` / :py:func:`shared_manifold` / :py:func:`shared_corewise`.
   The wrapper is stateless up to its static ``(base, sharing)`` identity (value-based
   ``__eq__``/``__hash__``, so it is a stable jit aux); the per-frame companion
   (:py:class:`~t3toolbox.backend.sharing.SharedFrameData`) is DERIVED from a frame on
   demand -- pass it explicitly (``shared_data=``) to amortize across calls at one frame, as
   the fitting models do via :py:meth:`precompute`.

   On a MANIFOLD base the full surface is available (``frame``/``project``/``project_oblique``/
   ``inner``/``norm``/``retract``/``project_ambient``/``transport``/``randn``); on a COREWISE
   base the surface matches the base (no ambient projection / transport). Safe mode enforces
   the base geometry's preconditions plus tied factors at ``frame``/``retract``/``transport``
   entry. Full shared rank is deliberately NOT a precondition -- zero-padded continuation
   restarts sit on the lower-shared-rank stratum by construction, and the tied projection's
   clipped solve is well-defined (minimum-norm) there.

   .. rubric:: Examples

   >>> import numpy as np
   >>> import t3toolbox.tucker_tensor_train as t3
   >>> import t3toolbox.manifold as t3m
   >>> import t3toolbox.shared_geometry as sg
   >>> np.random.seed(0)
   >>> x = t3.TuckerTensorTrain.randn((6, 6, 5), (3, 3, 2), (1, 2, 2, 1)).share((0, 0, 1))
   >>> geom = sg.shared_manifold((0, 0, 1))
   >>> frame = geom.frame(x)                       # safe-mode tied check + orthonormal frame
   >>> v = geom.randn(frame)                       # a standard Gaussian on the TIED tangent space
   >>> print(v.is_gauged())
   True
   >>> y = geom.retract(v)                         # grouped retraction: stays exactly tied
   >>> print(y.data[0][0] is y.data[0][1])
   True
   >>> y0 = geom.retract(t3m.T3Tangent.zeros(frame))
   >>> print(bool(np.allclose(y0.to_dense(), x.to_dense())))   # retract(0) == the base point
   True


   .. py:attribute:: base


   .. py:attribute:: sharing


   .. py:property:: base_name
      :type: str



   .. py:property:: is_uniform
      :type: bool


      True when the base is a uniform geometry singleton (points/tangents are uniform objects).

Methods
-------

.. autoapisummary::

   t3toolbox.shared_geometry.SharedGeometry.__eq__
   t3toolbox.shared_geometry.SharedGeometry.__hash__
   t3toolbox.shared_geometry.SharedGeometry.__repr__
   t3toolbox.shared_geometry.SharedGeometry.groups
   t3toolbox.shared_geometry.SharedGeometry.frame
   t3toolbox.shared_geometry.SharedGeometry.shared_frame_data
   t3toolbox.shared_geometry.SharedGeometry.precompute
   t3toolbox.shared_geometry.SharedGeometry.project
   t3toolbox.shared_geometry.SharedGeometry.project_oblique
   t3toolbox.shared_geometry.SharedGeometry.inner
   t3toolbox.shared_geometry.SharedGeometry.norm
   t3toolbox.shared_geometry.SharedGeometry.randn
   t3toolbox.shared_geometry.SharedGeometry.randn_like
   t3toolbox.shared_geometry.SharedGeometry.retract
   t3toolbox.shared_geometry.SharedGeometry.project_ambient
   t3toolbox.shared_geometry.SharedGeometry.transport