sharing
=======


.. py:module:: t3toolbox.backend.sharing

.. autoapi-nested-parse::

   Shared Tucker factors (SF-T3): the sharing partition, the tied-factors checkers, and the
   per-frame companion.

   ``validate_sharing`` canonicalizes a per-mode label spec into the static ``groups`` form;
   ``t3_sharing_residual`` / ``t3_tucker_factors_shared`` are the non-enforcing tied-factors
   checkers (the safe-mode precondition behind the shared operations); ``t3_tie_tucker_factors``
   is the plain per-group mean (drift repair for nearly-tied POINTS -- never the metric
   projection of a tangent, which is geometry-specific and lives with the shared geometry).
   ``fv_shared_frame_data`` derives the :py:class:`SharedFrameData` companion from an
   orthogonal frame -- the per-group center cores and the thin SVD of the stacked ``S`` factors
   that the shared geometry's projection, retraction, and spectrum diagnostics consume.

   A shared T3 is an ordinary Tucker tensor train whose Tucker factors are equal within
   user-specified groups of modes -- the SF-ETT decomposition of Molozhavenko & Rakhuba (2026),
   "Optimization on the extended tensor-train manifold with shared factors" (Comput. Appl. Math.
   45:221), generalized to an arbitrary partition of the modes into sharing groups. The
   shared-factor format originates with SF-Tucker: Peshekhonov, Arzhantsev & Rakhuba (2024),
   "Training a Tucker model with shared factors: a Riemannian optimization approach"
   (AISTATS, PMLR 238).



Classes
-------

.. toctree::
   :hidden:

   /autoapi/t3toolbox/backend/sharing/SharedFrameData

.. autoapisummary::

   t3toolbox.backend.sharing.SharedFrameData


Functions
---------

.. toctree::
   :hidden:

   /autoapi/t3toolbox/backend/sharing/validate_sharing
   /autoapi/t3toolbox/backend/sharing/canonical_groups
   /autoapi/t3toolbox/backend/sharing/nontrivial_groups
   /autoapi/t3toolbox/backend/sharing/groups_to_labels
   /autoapi/t3toolbox/backend/sharing/t3_sharing_residual
   /autoapi/t3toolbox/backend/sharing/t3_tucker_factors_shared
   /autoapi/t3toolbox/backend/sharing/t3_tie_tucker_factors
   /autoapi/t3toolbox/backend/sharing/ut3_tie_tucker_factors
   /autoapi/t3toolbox/backend/sharing/fv_shared_frame_data
   /autoapi/t3toolbox/backend/sharing/fv_share_tucker_variations
   /autoapi/t3toolbox/backend/sharing/fv_tied_ambient_directions
   /autoapi/t3toolbox/backend/sharing/fv_share_tucker_variations_corewise
   /autoapi/t3toolbox/backend/sharing/fv_tied_variations_residual
   /autoapi/t3toolbox/backend/sharing/ut3_sharing_residual
   /autoapi/t3toolbox/backend/sharing/ut3_tucker_factors_shared
   /autoapi/t3toolbox/backend/sharing/ufv_shared_frame_data
   /autoapi/t3toolbox/backend/sharing/ufv_share_tucker_variations
   /autoapi/t3toolbox/backend/sharing/ufv_share_tucker_variations_corewise
   /autoapi/t3toolbox/backend/sharing/ufv_tied_variations_residual
   /autoapi/t3toolbox/backend/sharing/t3_tucker_weights_sharing_residual
   /autoapi/t3toolbox/backend/sharing/t3_tucker_weights_shared
   /autoapi/t3toolbox/backend/sharing/ut3_tucker_weights_sharing_residual
   /autoapi/t3toolbox/backend/sharing/ut3_tucker_weights_shared

.. autoapisummary::

   t3toolbox.backend.sharing.validate_sharing
   t3toolbox.backend.sharing.canonical_groups
   t3toolbox.backend.sharing.nontrivial_groups
   t3toolbox.backend.sharing.groups_to_labels
   t3toolbox.backend.sharing.t3_sharing_residual
   t3toolbox.backend.sharing.t3_tucker_factors_shared
   t3toolbox.backend.sharing.t3_tie_tucker_factors
   t3toolbox.backend.sharing.ut3_tie_tucker_factors
   t3toolbox.backend.sharing.fv_shared_frame_data
   t3toolbox.backend.sharing.fv_share_tucker_variations
   t3toolbox.backend.sharing.fv_tied_ambient_directions
   t3toolbox.backend.sharing.fv_share_tucker_variations_corewise
   t3toolbox.backend.sharing.fv_tied_variations_residual
   t3toolbox.backend.sharing.ut3_sharing_residual
   t3toolbox.backend.sharing.ut3_tucker_factors_shared
   t3toolbox.backend.sharing.ufv_shared_frame_data
   t3toolbox.backend.sharing.ufv_share_tucker_variations
   t3toolbox.backend.sharing.ufv_share_tucker_variations_corewise
   t3toolbox.backend.sharing.ufv_tied_variations_residual
   t3toolbox.backend.sharing.t3_tucker_weights_sharing_residual
   t3toolbox.backend.sharing.t3_tucker_weights_shared
   t3toolbox.backend.sharing.ut3_tucker_weights_sharing_residual
   t3toolbox.backend.sharing.ut3_tucker_weights_shared