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

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


Attributes
----------

.. autoapisummary::

   sequince.steps.mutation.base.LogProbFn
   sequince.steps.mutation.base.PARTICLE_TRANSFORM_KEY
   sequince.steps.mutation.base.TransformRefit


Classes
-------

.. autoapisummary::

   sequince.steps.mutation.base.MutationStep


Functions
---------

.. autoapisummary::

   sequince.steps.mutation.base.call_log_prob
   sequince.steps.mutation.base.as_scalar_log_prob
   sequince.steps.mutation.base.as_vector_log_prob


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

.. py:data:: LogProbFn

.. py:data:: PARTICLE_TRANSFORM_KEY
   :value: 'particle_transform'


.. py:data:: TransformRefit

.. py:function:: call_log_prob(fn, position, context)

.. py:function:: as_scalar_log_prob(value)

.. py:function:: as_vector_log_prob(value, length)

.. py:class:: MutationStep(log_prob_fn, *, transform = None, transform_refit = 'always', store_chains = False, metrics = ())

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


   Base class for mutations that optionally operate in transformed space.

   ``transform_refit`` controls whether a cloned transform is fitted for every
   mutation call, once per outer :class:`StepContext`, or only once for the
   lifetime of this mutation step. A callable can instead request fits based
   on the particles and context. It is evaluated once per mutation
   application, including the initial fit, and may consume or reset a trigger
   stored in the context.


   .. py:attribute:: metrics


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


      Default transition count for one standalone application.


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


      Run transitions within a block without finalizing metrics.

      Pass ``mutation_state=None`` to initialize a new block; otherwise pass
      the state returned by the preceding call. The state holds individual
      metric states and cumulative acceptance bookkeeping. It must belong
      to the same metric configuration and mutation coordinate space.

      Returns ``(state, context, output, mutation_state)``. The output's
      metrics remain unset, including on the first and zero-step calls.
      Concrete mutations prepare existing metrics on entry, update state for each
      transition, and return it explicitly without calling metric.result().
      Runtime state must never be stored on the mutation object.

      Use ``apply`` or ``apply_with_n_steps`` for a complete standalone block.
      RepeatedMutationStep uses this method to continue across rounds and
      finalizes metrics once after the complete block.



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

      Run a complete fixed-length block and finalize its configured metrics.



   .. py:property:: store_chains
      :type: bool


      Whether full mutation chains are included in step outputs.


   .. py:method:: state_dict()

      Return the fitted transform and the context identifying its fit.



   .. py:method:: load_state_dict(state)

      Restore the transform cache; legacy empty state clears the cache.



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

      Initialize cached target data and functional transform state.