ValueHashedFields
=================

.. toctree::
   :hidden:

   /autoapi/t3toolbox/backend/common/ValueHashedFields.require_parameters_are_fields
   /autoapi/t3toolbox/backend/common/ValueHashedFields.__hash__
   /autoapi/t3toolbox/backend/common/ValueHashedFields.__eq__

.. py:class:: t3toolbox.backend.common.ValueHashedFields

   Mixin giving a frozen dataclass VALUE-based ``__hash__``/``__eq__`` over **all** its fields,
   with numpy arrays compared by CONTENT rather than by identity.

   The generalization of :py:class:`ValueHashedMasks` (which value-hashes one designated ``.data``
   tuple of masks) to a dataclass whose *parameters are its fields*. Both exist for the same reason:
   the object rides as jax ``aux_data``, so its ``__hash__``/``__eq__`` are part of the jit
   compilation cache key, and identity semantics make a rebuilt-but-identical object a NEW key ->
   jit RECOMPILES. A geometry rebuilt at each rank-continuation level, or a sampling kind rebuilt at
   each outer step, must be the SAME cache key when its parameters are the same.

   Use it instead of the dataclass ``eq=True`` default whenever a field may hold a numpy array
   (``eq=True`` would raise "truth value of an array is ambiguous"), and instead of ``eq=False``
   whenever the object is a jit aux (identity semantics recompile). Subclasses must be
   ``@dataclass(frozen=True, eq=False)``.

   The alternative this replaces is a hand-maintained parallel ``identity`` tuple restating the
   fields -- correct while someone keeps it in sync, silently identity-based for a user-built object
   that omits it. Here the fields ARE the key, so there is nothing to keep in sync.

Methods
-------

.. autoapisummary::

   t3toolbox.backend.common.ValueHashedFields.require_parameters_are_fields
   t3toolbox.backend.common.ValueHashedFields.__hash__
   t3toolbox.backend.common.ValueHashedFields.__eq__