validate_sharing
================

.. py:function:: t3toolbox.backend.sharing.validate_sharing(sharing, shape)

   .. code-block:: python

      def validate_sharing(
              sharing:    typ.Sequence,       # len=d, static; one hashable group label per mode, e.g. (0, 1, 1)
              shape:      typ.Sequence[int],  # (N0, ..., N(d-1)); modes sharing a label need equal sizes
      ) -> typ.Tuple[typ.Tuple[int, ...], ...]:  # groups, static; mode indices per group (canonical form)


   Validate a sharing partition and return its canonical ``groups`` form.

   ``sharing`` assigns one hashable group label per mode; modes with equal labels share one
   Tucker factor. The canonical form lists each group's mode indices (ascending), groups
   ordered by first mode, singleton groups included -- static structure (a jit aux / closure
   constant), never traced. Structural problems -- wrong length, unhashable labels, unequal
   mode sizes within a group -- raise unconditionally (both safety modes).

   .. rubric:: Examples

   Labels are arbitrary hashables; groups come back as mode-index tuples, ordered by first
   mode, singletons included:

   >>> import t3toolbox.backend.sharing as sharing
   >>> sharing.validate_sharing((0, 1, 1, 2, 2, 2), (4, 5, 5, 6, 6, 6))
   ((0,), (1, 2), (3, 4, 5))
   >>> sharing.validate_sharing(('in', 'out', 'in'), (7, 5, 7))   # non-adjacent groups are fine
   ((0, 2), (1,))

   Gotcha: modes in a group must have equal mode sizes (a shared factor needs one ambient
   dimension) -- a mismatch is a structural error:

   >>> sharing.validate_sharing((0, 0), (4, 5))   # doctest: +IGNORE_EXCEPTION_DETAIL
   Traceback (most recent call last):
       ...
   ValueError