sequince.steps.base
===================

.. py:module:: sequince.steps.base


Classes
-------

.. autoapisummary::

   sequince.steps.base.FixedLengthMutation
   sequince.steps.base.DynamicBudgetMutation
   sequince.steps.base.SMCStep


Functions
---------

.. autoapisummary::

   sequince.steps.base.validate_n_steps


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

.. py:function:: validate_n_steps(n_steps)

   Validate a caller-supplied fixed mutation length.


.. py:class:: FixedLengthMutation

   Bases: :py:obj:`Protocol`


   Capability for mutation-like steps accepting a per-call transition count.

   ``n_steps`` is a host-side integer. Backends such as JAX therefore require it
   to be static while tracing or compiling a call.


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


.. py:class:: DynamicBudgetMutation

   Bases: :py:obj:`Protocol`


   Functional mutation with a runtime budget and static history capacity.

   The scalar integer array budget must lie in [0, max_steps]. Initialize the
   functional state/context and metadata before tracing. The returned metric
   state continues an enclosing block; only its owner finalizes metrics.
   ``random_state`` is the backend-native state returned by
   ``orng.RandomGenerator.state()``; for JAX it is a PRNG key array. Functional
   calls accept and return that state, while eager methods accept the ORNG
   generator object. Configuration validation accepts an optional ``max_steps``
   override so enclosing adapters validate the effective history capacity rather
   than the child's default sweep count.


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



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


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


   .. py:method:: validate_functional_configuration(config, state, *, max_steps = None)


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


.. py:class:: SMCStep

   Base class for steps with explicit context and output returns.

   Functional steps request immediate stopping through StepContext. The runner
   conditionally skips later steps, which must have initialized, fixed-structure
   functional carries under JAX.


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



   .. 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:: validate_functional_configuration(config, state)

      Validate host-side pipeline settings before initializing any step.

      :param config: Read-only runner configuration, including the complete pipeline.
      :type config: SMCConfig
      :param state: Initial particle state, including the population shape.
      :type state: ParticleState

      .. rubric:: Notes

      Override to reject incompatible pipeline settings. Metadata and cache
      preparation belong in the existing functional initialization hooks.



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

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



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



