sequince.density
================

.. py:module:: sequince.density

.. autoapi-nested-parse::

   Callable-based sequential and tempered target densities.



Classes
-------

.. autoapisummary::

   sequince.density.SequentialDensity
   sequince.density.TemperedDensity


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

.. py:class:: SequentialDensity(log_prob, log_increment, *, evaluation_key = None)

   Bases: :py:obj:`_DensityComponents`, :py:obj:`sequince.target.SequentialTarget`


   Sequential target defined by density and increment callables.

   ``log_prob`` returns the current target log density for MCMC;
   ``log_increment`` returns the complete weight increment. Both accept
   particles and optionally context. Weighting calls only the increment.
   MCMC evaluates and caches ``log_prob`` separately.

   For context-dependent densities, supply ``evaluation_key(context)`` to
   identify the stage relevant to cached density values, or explicitly refresh
   the evaluation when the density changes. Keys must be hashable; compiled
   execution requires static keys.


   .. py:method:: evaluation_components(context)

      Components needed for a full density evaluation, when known.

      These are the components used to compute ``log_prob``, such as during
      MCMC. They need not include every component the target supports:
      ``log_increment`` is included only when the density itself requires it.
      Other components can still be requested explicitly through
      ``prepare_evaluation(components=...)``.

      When ``components=None``, preparation uses this declaration to complete
      a partial cache and retain only these components. Returning None
      preserves the default full-evaluation contract for custom targets.



   .. py:method:: log_prob(particles, context, *, evaluation=None)

      Return the current target log density.



   .. py:method:: log_increment(particles, context, *, evaluation=None)

      Return the log-weight increment to the next target.



.. py:class:: TemperedDensity(log_initial, log_density_ratio, *, evaluation_key = None)

   Bases: :py:obj:`_DensityComponents`, :py:obj:`sequince.target.TemperedTarget`


   Tempered target defined by an initial density and a log-density ratio.

   ``log_initial`` and ``log_density_ratio`` accept particles and optionally
   context. The target density is ``log_initial + beta * log_density_ratio``.
   Weighting evaluates only the increment, reusing it from a compatible MCMC
   evaluation when available. MCMC evaluates and caches both components.

   ``evaluation_key`` has the same meaning as for ``SequentialDensity``;
   beta alone does not invalidate these endpoint components.


   .. py:method:: log_initial(particles, context, *, evaluation=None)

      Return the initial endpoint log density.



   .. py:method:: log_terminal(particles, context, *, evaluation=None)

      Return the terminal endpoint log density.



   .. py:method:: log_increment(particles, context, *, evaluation=None)

      Return the terminal-to-initial log-density ratio.



   .. py:method:: log_prob(particles, context, *, evaluation=None)

      Return the current target log density.