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:: validate_functional_configuration(config, state, *, max_steps = None)

      Validate each child once with its effective per-round capacity.



   .. py:method:: initialize_functional_metadata(state, metadata)

      Return metadata with fields required by ``apply_functional``.



   .. py:method:: apply_functional(state, context, random_state)

      Apply a functional step to particle step.

      This returns the updated state, context, next random state, and any
      additional outputs.

      This method is intended for use in functional SMC iterations where the
      random state is explicitly threaded through the computation. Pass the
      backend-native state returned by ``orng.RandomGenerator.state()``;
      for JAX this is a PRNG key array. An ORNG wrapper is reconstructed
      internally, and its advanced state is returned to the caller.



   .. py:method:: apply_dynamic_budget(state, context, random_state, *, n_steps, max_steps, mutation_state = None)

      Split a runtime total by quotient/remainder and share metric state.

      Round capacities use the same split of max_steps, so their sum is
      exactly max_steps. Each round exposes its own executed count.
      Post-round steps run even for zero-budget rounds.



   .. 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`.



