sequince.steps.mutation.repeated
================================

.. py:module:: sequince.steps.mutation.repeated

.. autoapi-nested-parse::

   Complete mutation blocks with explicit rounds and metric ownership.



Classes
-------

.. autoapisummary::

   sequince.steps.mutation.repeated.RepeatedMutationStepOutput
   sequince.steps.mutation.repeated.RepeatedMutationStep


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

.. py:class:: RepeatedMutationStepOutput

   Mutation and post-round outputs plus one complete diagnostic record.


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


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


   .. py:attribute:: metrics
      :type:  sequince.steps.mutation.metrics.MutationMetricsOutput | None


.. py:class:: RepeatedMutationStep(mutation, *, n_rounds = 1, n_steps = None, after_round = None)

   Bases: :py:obj:`sequince.steps.base.SMCStep`


   Run fixed mutation rounds with one shared collection of metric states.

   ``n_steps`` is the total default budget. If omitted, use the child's
   configured length times ``n_rounds``. ``apply_with_n_steps`` overrides the
   total for a single call. Budgets are divided evenly, with the remainder
   assigned to the first rounds.

   ``after_round`` is an ordinary SMCStep, executed after every round,
   including zero-step rounds and the final round. It never receives metric
   state. The mutation refreshes references on entering the following round
   without recording the intervening displacement or changing frozen scaling.

   Metrics are configured on the mutation child. Runtime state is local to
   the block call and passed explicitly through the rounds. Nested blocks
   share the same state and only the outermost block finalizes metrics.
   Fixed schedules execute all rounds even if a child requests stopping;
   the stop flags remain available to the enclosing SMC runner.


   .. py:attribute:: n_rounds
      :value: 1



   .. py:attribute:: mutation


   .. py:attribute:: after_round
      :value: None



   .. py:property:: n_steps
      :type: int


      Default total number of transitions across all rounds.


   .. py:property:: metrics
      :type: sequince.steps.mutation.metrics.MutationMetrics


      Static metric configuration owned by the mutation child.


   .. py:method:: apply(state, context, rng)


   .. py:method:: apply_with_n_steps(state, context, rng, *, n_steps)


   .. py:method:: apply_with_mutation_state(state, context, rng, *, n_steps, mutation_state = None)

      Run all rounds and return mutation state without finalizing it.

      ``None`` starts a new block. An existing state continues an enclosing
      block, preserving its metric scaling and cumulative bookkeeping.



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

      Return shape-complete inputs for ``apply_functional``.

      Steps whose functional output adds array leaves should initialize
      matching leaves here so one compiled signature can be reused from the
      first iteration onward.



   .. py:method:: state_dict()

      Return mutable state required by subsequent SMC iterations.



   .. py:method:: load_state_dict(state)

      Restore state produced by :meth:`state_dict`.