sequince.state
==============

.. py:module:: sequince.state


Classes
-------

.. autoapisummary::

   sequince.state.ParticleState
   sequince.state.PersistentParticleState


Functions
---------

.. autoapisummary::

   sequince.state.normalize_log_weights


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

.. py:function:: normalize_log_weights(log_weights, *, xp = None)

   Return normalized log weights and their array scalar normalizer.


.. py:class:: ParticleState(particles, log_weights = None, log_normalizing_constant = 0.0, initial_ancestor_indices = None, evaluation = None, metadata = None)

   Container for particle locations, log weights, and auxiliary information.

   ``log_normalizing_constant`` is the accumulated estimate of ``log Z`` for
   the SMC target sequence. For Bayesian posterior SMC this is the log
   evidence; for particle filtering it is the log marginal likelihood of the
   observation sequence.


   .. py:attribute:: particles
      :type:  sequince.typing.Array


   .. py:attribute:: log_weights
      :type:  sequince.typing.Array


   .. py:attribute:: initial_ancestor_indices
      :type:  sequince.typing.Array


   .. py:attribute:: log_normalizing_constant
      :type:  float
      :value: 0.0



   .. py:attribute:: evaluation
      :type:  sequince.target.TargetEvaluation | None
      :value: None



   .. py:attribute:: metadata
      :type:  MutableMapping[str, Any]


   .. py:property:: log_evidence
      :type: float


      Alias for ``log_normalizing_constant``.


   .. py:method:: copy()

      Return a copy of the state preserving the array backend.



   .. py:method:: normalize()

      Return a new state and its incremental log normalizing constant.



   .. py:property:: weights
      :type: sequince.typing.Array


      Return normalized weights.


   .. py:method:: effective_sample_size()

      Compute the effective sample size (ESS).



   .. py:method:: with_updates(**kwargs)

      Return a copy of the state with selective updates applied.



   .. py:method:: replace_particles(particles, *, evaluation = None, **updates)

      Replace particles and explicitly provide their evaluation.



   .. py:method:: resample(indices)

      Return a resampled state using the provided ancestor indices.



   .. py:method:: to_dict()

      Return a detached dictionary representation of this state.



   .. py:method:: from_dict(payload)
      :classmethod:


      Reconstruct a state from :meth:`to_dict` output.



   .. py:method:: encode_for_hdf5()

      Return a versioned, portable particle-state payload.



   .. py:method:: save(h5_file_or_group, path = 'state')

      Save this state below ``path`` in an open HDF5 handle.



   .. py:method:: load(h5_file_or_group, path = 'state')
      :classmethod:


      Load a built-in state from ``path`` in an open HDF5 handle.



.. py:class:: PersistentParticleState(particles, betas, log_normalizing_constants, batch_size, *, log_weights = None, log_normalizing_constant = None, initial_ancestor_indices = None, evaluation = None, metadata = None)

   Bases: :py:obj:`ParticleState`


   Equal-sized particle batches retained from historical targets.

   ``log_normalizing_constants`` contains normalizing-constant estimates for
   targets which generated archived batches. The scalar
   ``log_normalizing_constant`` follows the ordinary :class:`ParticleState`
   interface and may instead describe a new target toward which the archive
   has just been weighted.


   .. py:attribute:: betas
      :type:  sequince.typing.Array


   .. py:attribute:: log_normalizing_constants
      :type:  sequince.typing.Array


   .. py:attribute:: batch_size
      :type:  int


   .. py:property:: log_evidence
      :type: float


      Alias for ``log_normalizing_constant``.


   .. py:property:: log_evidences
      :type: sequince.typing.Array


      Alias for ``log_normalizing_constants``.


   .. py:property:: n_particles
      :type: int


      Return the total number of retained particles.


   .. py:property:: n_batches
      :type: int


      Return the number of historical particle batches.


   .. py:method:: from_state(state, *, beta, log_normalizing_constant)
      :classmethod:


      Create a one-batch history from an active particle state.



   .. py:method:: copy()

      Return an independent copy preserving the persistent structure.



   .. py:method:: with_updates(**kwargs)

      Return a copy with non-structural fields updated.

      Historical particles and their batch metadata can only change through
      :meth:`append`. Persistent weighting steps may update ``log_weights``;
      callers may also replace compatible evaluations or metadata.



   .. py:method:: append(state, *, beta, log_normalizing_constant)

      Return a new history with one equal-sized batch appended.

      Ancestor indices are concatenated without offsets because every batch
      retains its genealogy relative to the same initial active population.



   .. py:method:: to_dict()

      Return a detached dictionary including persistent history.



   .. py:method:: from_dict(payload)
      :classmethod:


      Reconstruct a persistent state from :meth:`to_dict` output.



   .. py:method:: encode_for_hdf5()

      Return a versioned payload including persistent history.