sequince.steps.mutation.metrics.rjd
===================================

.. py:module:: sequince.steps.mutation.metrics.rjd

.. autoapi-nested-parse::

   Relative jump distance in fixed, already-whitened mutation coordinates.



Classes
-------

.. autoapisummary::

   sequince.steps.mutation.metrics.rjd.RelativeJumpDistanceMetric


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

.. py:class:: RelativeJumpDistanceMetric

   Measure endpoint movement relative to a population reference distance.

   :param reference_radius: Positive fixed distance in whitened coordinates, default 1. The default
                            is an approximation; whitening alone does not imply this radius.
                            "pair_median" estimates the median distance between independent
                            empirical draws with replacement, including self pairs, once at block
                            initialization. This estimator does not perform clustering.
   :type reference_radius: float or {"pair_median"}
   :param name: Result key in MutationMetricsOutput.values, default "rjd".
   :type name: str
   :param seed: Independent diagnostic seed, default 0. Reset on each initialization
                for reproducible radii without consuming the mutation RNG.
   :type seed: int
   :param n_pairs: Number of sampled pairs for "pair_median", default 4096.
   :type n_pairs: int

   .. rubric:: Notes

   Input must already be whitened. Particle identities and the coordinate
   system must remain fixed across all segments of a block: do not reorder,
   resample, or refit transforms between segments. Endpoint displacement
   includes intervening steps when they preserve this interpretation.
   Weights are not used: diagnostics describe the equally counted chains.

   Outputs are scalar arrays: fraction_above_one, geometric_mean and
   reference_radius. A zero-distance chain makes the geometric mean zero.
   Fixed radii support functional/JIT initialization. Pair-median
   initialization is eager and uses O(n_pairs * D) memory; subsequent metric
   updates support JIT. Only two populations and the frozen radius are retained.
   It is an SMC heuristic, not Buchner's neighbour-radius estimator.
   No mode consumes mutation RNG draws or adds target evaluations.

   Based on Buchner (2024), https://arxiv.org/abs/2402.11936.


   .. py:attribute:: reference_radius
      :type:  float | Literal['pair_median']
      :value: 1.0



   .. py:attribute:: name
      :type:  str
      :value: 'rjd'



   .. py:attribute:: seed
      :type:  int
      :value: 0



   .. py:attribute:: n_pairs
      :type:  int
      :value: 4096



   .. py:method:: initialize(particles, log_weights, context)

      Freeze the starting population and radius for one complete block.



   .. py:method:: prepare(state, particles, context)

      Continue the same block without resetting its start or radius.



   .. py:method:: update(state, particles, accepted, context, *, transition = None)

      Retain the latest endpoint, including unchanged rejected chains.



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

      Return endpoint RJD summaries without retaining particle histories.