geometry
========


.. py:module:: t3toolbox.backend.geometry

.. autoapi-nested-parse::

   Backend geometries on raw data -- the *where you optimize* axis of a fit.

   A geometry bundles the chart-level choices an optimizer needs and nothing else: the linearization
   ``frame``, the gauge projection ``project`` (``Pi``), the ``retract``, the coordinate ``inner``, and the
   optional per-frame ``precompute`` companion. The frontend twins are
   :py:class:`t3toolbox.manifold.ManifoldGeometry` / ``CorewiseGeometry`` and their uniform counterparts;
   these are the check-free versions a raw-``.data`` user calls directly.

   **Parameters are fields, not closures.** Each geometry is a frozen dataclass whose fields *are* its
   defining data -- the mode ``shape``, the rank ``masks`` it is fixed at, and the sharing ``groups``. This
   matters for more than tidiness: a geometry rides as jax ``aux_data``, so its ``__hash__``/``__eq__`` are
   part of the jit compilation cache key. With the parameters sealed in closure cells (the previous
   ``GeometryOps`` record-of-lambdas) a rebuilt-but-identical geometry was always a *new* key, so every
   rank-continuation level and every rebuilt model recompiled. Value-based hash/eq over the fields
   (:py:class:`~t3toolbox.backend.common.ValueHashedFields`) makes the cache key reflect the geometry's
   actual identity. Mathematically it is also the more faithful encoding: a uniform manifold *at a given
   rank* is a different manifold from one at another rank, so the rank belongs in the object's data.

   **The math stays reachable.** Per the backend rule, a method here only binds parameters and names a
   role -- every line of actual math is also a standalone function, either in the operation modules
   (:py:mod:`~t3toolbox.backend.tv_operations`, :py:mod:`~t3toolbox.backend.utv_operations`,
   :py:mod:`~t3toolbox.backend.sharing`) or named in this module
   (:py:func:`fv_base_point_tangent`, :py:func:`ufv_base_point_tangent`,
   :py:func:`t3_left_orthogonal_norm_sq`, :py:func:`t3_alias_tied_tucker_factors`).

   **Sharing is a field, not a wrapper.** ``groups=()`` is the ordinary geometry; a non-empty partition
   restricts every projection to the TIED tangent subspace and keeps the retraction on the shared set
   (SF-T3; ``docs/sharing.md``). One class, one code path. Build the canonical partition with
   :py:func:`~t3toolbox.backend.sharing.validate_sharing`, or use the ``from_point`` /
   ``with_sharing`` constructors here.



Attributes
----------

.. autoapisummary::

   t3toolbox.backend.geometry.canonical_groups


Classes
-------

.. toctree::
   :hidden:

   /autoapi/t3toolbox/backend/geometry/ManifoldGeometryOps
   /autoapi/t3toolbox/backend/geometry/CorewiseGeometryOps
   /autoapi/t3toolbox/backend/geometry/UniformManifoldGeometryOps
   /autoapi/t3toolbox/backend/geometry/UniformCorewiseGeometryOps

.. autoapisummary::

   t3toolbox.backend.geometry.ManifoldGeometryOps
   t3toolbox.backend.geometry.CorewiseGeometryOps
   t3toolbox.backend.geometry.UniformManifoldGeometryOps
   t3toolbox.backend.geometry.UniformCorewiseGeometryOps


Functions
---------

.. toctree::
   :hidden:

   /autoapi/t3toolbox/backend/geometry/t3_left_orthogonal_norm_sq
   /autoapi/t3toolbox/backend/geometry/fv_base_point_tangent
   /autoapi/t3toolbox/backend/geometry/ufv_base_point_tangent
   /autoapi/t3toolbox/backend/geometry/t3_alias_tied_tucker_factors

.. autoapisummary::

   t3toolbox.backend.geometry.t3_left_orthogonal_norm_sq
   t3toolbox.backend.geometry.fv_base_point_tangent
   t3toolbox.backend.geometry.ufv_base_point_tangent
   t3toolbox.backend.geometry.t3_alias_tied_tucker_factors


Module Contents
---------------

.. py:data:: canonical_groups