sequince.steps.mutation.metrics.base
====================================

.. py:module:: sequince.steps.mutation.metrics.base

.. autoapi-nested-parse::

   Metric interfaces and collection lifecycle.



Classes
-------

.. autoapisummary::

   sequince.steps.mutation.metrics.base.MutationMetric
   sequince.steps.mutation.metrics.base.MutationMetrics


Module Contents
---------------

.. py:class:: MutationMetric

   Bases: :py:obj:`Protocol`


   Static metric configuration with explicit, fixed-structure pytree state.

   ``update`` must be pure: (old state, transition) -> new state. Never
   mutate Python attributes or input arrays. Arrays, tuples, dictionaries and
   registered pytree dataclasses are all valid states. Shapes and dtypes must
   remain fixed under JIT. ``accepted`` is a per-particle boolean mask.

   An optional ``prepare(state, particles, context)`` method prepares existing
   state for the next mutation segment, preserving accumulated measurements.
   It must return state without mutating its input; absent means no-op.

   Every update accepts the keyword-only ``transition`` argument. Metrics
   needing displacement and kernel auxiliary declare ``needs_transition = True``;
   otherwise mutations may omit this work and pass None. The flag is optional
   and defaults to False. Auxiliary data remains opaque to the collection.


   .. py:property:: name
      :type: str



   .. py:method:: initialize(particles, log_weights, context)


   .. py:method:: update(state, particles, accepted, context, *, transition = None)


   .. py:method:: result(state, context)


.. py:class:: MutationMetrics(metrics = ())

   Static metric collection with pure operations on MutationStepState.

   Initialize once per block, update once per population transition, and
   compute results only at the complete block boundary. Preparing the next
   segment preserves accumulated measurements. The collection holds
   configuration only; runtime state is always returned explicitly.


   .. py:attribute:: needs_transition
      :type:  bool


   .. py:method:: initialize(particles, log_weights, context)

      Initialize metric state and zero acceptance counters for a new block.



   .. py:method:: prepare(metric_state, particles, context)

      Prepare existing metric state for the next segment, retaining totals.



   .. py:method:: update(metric_state, particles, accepted, context, *, transition = None)

      Record one population transition without changing the input state.



   .. py:method:: result(metric_state, context)

      Collect final results at the outermost block boundary.