sequince.steps.mutation.metrics.rjd

sequince.steps.mutation.metrics.rjd#

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

Classes#

RelativeJumpDistanceMetric

Measure endpoint movement relative to a population reference distance.

Module Contents#

class sequince.steps.mutation.metrics.rjd.RelativeJumpDistanceMetric[source]#

Measure endpoint movement relative to a population reference distance.

Parameters:

  • reference_radius (float or {"pair_median"}) – 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.

  • name (str) – Result key in MutationMetricsOutput.values, default “rjd”.

  • seed (int) – Independent diagnostic seed, default 0. Reset on each initialization for reproducible radii without consuming the mutation RNG.

  • n_pairs (int) – Number of sampled pairs for “pair_median”, default 4096.

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.

reference_radius: float | Literal['pair_median'] = 1.0#
name: str = 'rjd'#
seed: int = 0#
n_pairs: int = 4096#
initialize(particles, log_weights, context)[source]#

Freeze the starting population and radius for one complete block.

Parameters:
Return type:

_RJDState

prepare(state, particles, context)[source]#

Continue the same block without resetting its start or radius.

Parameters:
Return type:

_RJDState

update(state, particles, accepted, context, *, transition=None)[source]#

Retain the latest endpoint, including unchanged rejected chains.

Parameters:
Return type:

_RJDState

result(state, context)[source]#

Return endpoint RJD summaries without retaining particle histories.

Parameters:
Return type:

dict[str, sequince.typing.Array]