sequince.steps.mutation.metrics.state
=====================================

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

.. autoapi-nested-parse::

   Immutable runtime state and completed mutation metrics.



Classes
-------

.. autoapisummary::

   sequince.steps.mutation.metrics.state.MutationMetricsOutput
   sequince.steps.mutation.metrics.state.MutationStepState
   sequince.steps.mutation.metrics.state.MutationTransition


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

.. py:class:: MutationMetricsOutput

   Core bookkeeping and named results for one complete mutation block.

   ``n_accepted`` counts accepted proposals for sampled transitions. Recycling
   algorithms integrating over accept/reject decisions report the expected
   count instead, which may be fractional.


   .. py:attribute:: n_steps
      :type:  Any


   .. py:attribute:: n_attempted
      :type:  Any


   .. py:attribute:: n_accepted
      :type:  Any


   .. py:attribute:: values
      :type:  collections.abc.Mapping[str, Any]


   .. py:property:: acceptance
      :type: Any



.. py:class:: MutationStepState

   Immutable pytree state for continuing a mutation block.

   Normally obtained from ``apply_with_mutation_state`` by passing ``None``
   for the initial state, then passed unchanged into the next call. ``states``
   holds individual metric states in configured metric order; the counters
   accumulate across the complete block. This is runtime state, not finalized
   metrics. Its pytree structure, leaf shapes and dtypes must remain fixed
   inside compiled loops.


   .. py:attribute:: states
      :type:  tuple[Any, ...]


   .. py:attribute:: n_steps
      :type:  Any


   .. py:attribute:: n_attempted
      :type:  Any


   .. py:attribute:: n_accepted
      :type:  Any


.. py:class:: MutationTransition

   One transition's accepted displacement and read-only kernel auxiliary.

   This ephemeral input is never retained by the metric collection.

   :param displacement: Accepted displacement in mutation coordinates with shape
                        ``(n_particles, n_dimensions)``, zero for rejected rows.
   :type displacement: array
   :param kernel_auxiliary: Read-only auxiliary information from the kernel sample, or None.
                            Red-blue sweeps restore particle-aligned leaves to population order.
   :type kernel_auxiliary: pytree, optional


   .. py:attribute:: displacement
      :type:  sequince.typing.Array


   .. py:attribute:: kernel_auxiliary
      :type:  Any
      :value: None