canonical_groups
================

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

   .. code-block:: python

      def canonical_groups(
              sharing:  typ.Optional[typ.Sequence],   # len=d group labels, or None
              shape:    typ.Tuple[int, ...],          # the mode sizes (group members must agree)
      ) -> typ.Tuple[typ.Tuple[int, ...], ...]:       # canonical partition, () when there is nothing to tie


   Normalize a ``sharing`` spec to a canonical partition, collapsing "nothing is tied" to ``()``.

   ``None`` and an all-singleton partition both give ``()``, so a consumer that stores the partition
   has exactly ONE representation of the unshared case -- which matters when the partition is part of
   an object's value identity (a jit ``aux_data`` key). :py:func:`validate_sharing` +
   :py:func:`nontrivial_groups` do the work; this just names the pairing, which callers otherwise
   open-code.