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

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


Classes
-------

.. autoapisummary::

   sequince.steps.base.FixedLengthMutation
   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:: 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.



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