sequince.steps.waste_free
=========================

.. py:module:: sequince.steps.waste_free

.. autoapi-nested-parse::

   Waste-free resampling and chain retention around an existing mutation.



Classes
-------

.. autoapisummary::

   sequince.steps.waste_free.WasteFreeResampleMove


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

.. py:class:: WasteFreeResampleMove(mutation, *, chain_length)

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


   Resample chain starts and retain a wrapped mutation's full chains.

   Implements the resampling and chain-retention portion of Algorithm 2 of
   Dau and Chopin [1]_. With N particles and chain length P, resample M=N/P
   starts using the input weights, run P-1 transitions and keep all P states
   per chain. Starts and repeated states after rejection are retained. No
   further resampling occurs inside this step; the output has N uniform
   weights and preserves the input evidence estimate.

   :param mutation: A MutationStep supporting apply_with_n_steps() and stored chains,
                    such as MetropolisHastingsMutation, BlackJAXMutation or MiniPCNMutation.
                    It owns the target, proposal, transforms and transition logic. One
                    complete block of P-1 steps is requested, overriding its default
                    n_steps for this call only. Chain storage is temporarily enabled and
                    its previous setting restored even if mutation fails.
   :param chain_length: Number P of retained states per chain, INCLUDING the start. Must be a
                        positive integer dividing N. P=1 only resamples; mutation is not called.

   .. rubric:: Examples

   With 1000 input particles, run 20 chains with 50 retained states each:

   >>> mutation = MetropolisHastingsMutation(target, GaussianRandomWalk(0.5))
   >>> step = WasteFreeResampleMove(mutation, chain_length=50)

   .. rubric:: References

   .. [1] Dau, H.-D. and Chopin, N. (2022). Waste-free Sequential Monte
      Carlo. JRSS B, 84(1), 114-148. https://doi.org/10.1111/rssb.12475
      Algorithm 2: https://arxiv.org/abs/2011.02328


   .. py:attribute:: mutation
      :type:  sequince.steps.mutation.MutationStep


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


   .. py:method:: state_dict()

      Forward the mutation's checkpoint state.



   .. py:method:: load_state_dict(state)

      Restore the wrapped mutation's checkpoint state.