sequince.steps.persistent
=========================

.. py:module:: sequince.steps.persistent

.. autoapi-nested-parse::

   Persistent particle archival and tempered importance weighting.

   See: https://arxiv.org/abs/2407.20722



Classes
-------

.. autoapisummary::

   sequince.steps.persistent.PersistParticles
   sequince.steps.persistent.PersistentTemperedWeighting
   sequince.steps.persistent.PersistentAdaptiveTemperedWeighting


Functions
---------

.. autoapisummary::

   sequince.steps.persistent.expected_unique_count
   sequince.steps.persistent.persistent_log_mixture_denominator
   sequince.steps.persistent.persistent_log_weights


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

.. py:function:: expected_unique_count(weights, n_active)

   Return multinomial expected unique entries for normalized weights.

   :param weights: Nonnegative, normalized floating-point weights (zeros are allowed).
   :type weights: array, shape (n_archive,)
   :param n_active: Positive number of draws with replacement.
   :type n_active: int

   :returns: Scalar expected unique count, on the input backend and device.
             This is only a diversity heuristic for systematic resampling.
   :rtype: array


.. py:function:: persistent_log_mixture_denominator(log_increment, betas, log_normalizing_constants, *, xp = None)

   Compute the log density of the equally weighted historical mixture.

   The common initial-target density is cancelled, leaving, for particle
   ``j``, ``logmeanexp(betas * log_increment[j] -
   log_normalizing_constants)``.


.. py:function:: persistent_log_weights(log_increment, betas, log_normalizing_constants, beta, *, xp = None)

   Compute unnormalised persistent importance weights.


.. py:class:: PersistParticles(target = None, *, n_particles = None)

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


   Archive populations in equal-sized batches.

   ``n_particles`` fixes the active batch size. The first state may contain
   any positive multiple of that size, with equal weights at beta zero.
   All initial batches are archived in one call. If omitted, infer the batch
   size from the first state, preserving the one-batch interface.


   .. py:attribute:: persistent_state
      :type:  sequince.state.PersistentParticleState | None
      :value: None



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


   .. py:method:: state_dict()

      Return the archive in checkpoint-friendly mapping form.



   .. py:method:: load_state_dict(state)

      Restore an archive produced by :meth:`state_dict`.



.. py:class:: PersistentTemperedWeighting(target, *, beta, refresh_components = ())

   Bases: :py:obj:`BasePersistentTemperedWeighting`


   Weight a persistent particle pool directly toward a fixed beta.


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


.. py:class:: PersistentAdaptiveTemperedWeighting(target, *, target_ess = 512, target_total_ess = None, dynamic = False, resample_at_end = False, beta_tolerance = 1e-06, max_bisection_iter = 30, refresh_components = ())

   Bases: :py:obj:`BasePersistentTemperedWeighting`


   Choose a persistent target beta using absolute archive ESS.

   The historical deterministic-mixture density is evaluated once, then the
   beta is bisected over the interval from the current beta to 1. If the
   requested ESS cannot be attained while advancing, the current
   beta is repeated so that another batch can be added to the archive.
   Once beta = 1 is selected, the weighting requests a
   runner stop. When ``target_total_ess`` is configured, beta = 1
   batches are instead accumulated until the complete archive reaches that
   ESS.

   :param target: Tempered target defining the persistent importance weights.
   :param target_ess: Desired effective sample size while selecting betas below 1.
   :param target_total_ess: Optional effective sample size required before stopping at beta = 1.
                            If omitted, stop when beta = 1 is first selected.
   :param dynamic: Adapt the integer ESS threshold for the next iteration using expected
                   multinomial unique entries. Defaults to False. The fixed reference is
                   set by the initial threshold; the terminal target never adapts.
   :type dynamic: bool, optional
   :param resample_at_end: If True, let downstream resampling and mutation generate a beta-one
                           batch before checking termination on the next archived, weighted state.
                           The terminal ESS requirement is checked after that batch is included.
                           Defaults to False, returning the terminal weighted archive immediately.
   :type resample_at_end: bool, optional
   :param beta_tolerance: Stop bisection once the beta bracket is no wider than this.
   :param max_bisection_iter: Maximum number of bisection iterations.
   :param refresh_components: Cached target-evaluation components to refresh before weighting.


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


   .. py:method:: state_dict()

      Save the next threshold and the fixed feedback reference.



   .. py:method:: load_state_dict(state)

      Load matching configuration; legacy empty state is static only.



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

      Reject functional execution because the archive grows dynamically.