ValueHashedMasks
================

.. toctree::
   :hidden:

   /autoapi/t3toolbox/backend/common/ValueHashedMasks.__hash__
   /autoapi/t3toolbox/backend/common/ValueHashedMasks.__eq__

.. py:class:: t3toolbox.backend.common.ValueHashedMasks

   Mixin giving uniform-layer mask holders VALUE-based ``__hash__``/``__eq__`` over mask content.

   Why this matters (PERFORMANCE, not cosmetics): a mask holder rides as jax ``aux_data``, so its
   ``__hash__``/``__eq__`` are part of the jit compilation cache key. Identity hash/eq (the bare
   ``@dataclass(eq=False)`` default) makes a fresh-but-array-identical holder a NEW key -> jit
   RECOMPILES. In a manifold-optimization loop the orthogonal frame is rebuilt every iteration (via
   ``ut3_orthogonal_representations``), producing fresh holders whose rank structure is identical;
   identity hashing would recompile every step, dwarfing the actual compute -- the opposite of the
   uniform layer's whole point. Value-based hash/eq makes the cache key reflect the rank STRUCTURE:
   identical structure -> cache hit (no recompile); genuinely different structure -> recompile (correct).
   See ``docs/contributor/uniform_pytree_composition.md``.

   Subclasses must be ``@dataclass(frozen=True, eq=False)`` and expose ``.data`` as a tuple of the
   (HOST numpy, concrete) mask arrays. The content hash is cached (the holder is frozen/immutable); eq
   short-circuits on identity, then compares by ``np.array_equal``.

Methods
-------

.. autoapisummary::

   t3toolbox.backend.common.ValueHashedMasks.__hash__
   t3toolbox.backend.common.ValueHashedMasks.__eq__