sequince.steps.persistent#

Persistent particle archival and tempered importance weighting.

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

Classes#

`PersistParticles`	Archive populations in equal-sized batches.
`PersistentTemperedWeighting`	Weight a persistent particle pool directly toward a fixed beta.
`PersistentAdaptiveTemperedWeighting`	Choose a persistent target beta using absolute archive ESS.

Functions#

`expected_unique_count`(weights, n_active)	Return multinomial expected unique entries for normalized weights.
`persistent_log_mixture_denominator`(log_increment, ...)	Compute the log density of the equally weighted historical mixture.
`persistent_log_weights`(log_increment, betas, ...[, xp])	Compute unnormalised persistent importance weights.

Module Contents#

sequince.steps.persistent.expected_unique_count(weights, n_active)[source]#

Return multinomial expected unique entries for normalized weights.

Parameters:

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

Returns:

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

Return type:

array

sequince.steps.persistent.persistent_log_mixture_denominator(log_increment, betas, log_normalizing_constants, *, xp=None)[source]#

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).

Parameters:

log_increment (sequince.typing.Array)
betas (sequince.typing.ArrayLike)
log_normalizing_constants (sequince.typing.Array)
xp (Any | None)

Return type:

sequince.typing.Array

sequince.steps.persistent.persistent_log_weights(log_increment, betas, log_normalizing_constants, beta, *, xp=None)[source]#

Compute unnormalised persistent importance weights.

Parameters:

log_increment (sequince.typing.Array)
betas (sequince.typing.ArrayLike)
log_normalizing_constants (sequince.typing.Array)
beta (sequince.typing.ArrayLike)
xp (Any | None)

Return type:

sequince.typing.Array

class sequince.steps.persistent.PersistParticles(target=None, *, n_particles=None)[source]#

Bases: 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.

Parameters:

target (sequince.target.Target | None)
n_particles (int | None)

persistent_state: sequince.state.PersistentParticleState | None = None#

apply(state, context, rng)[source]#

Parameters:

state (sequince.state.ParticleState)
context (sequince.steps.context.StepContext)
rng (orng.RandomGenerator)

Return type:

tuple[sequince.state.PersistentParticleState, sequince.steps.context.StepContext, None]

state_dict()[source]#

Return the archive in checkpoint-friendly mapping form.

Return type:: dict[str, Any]

load_state_dict(state)[source]#

Restore an archive produced by state_dict().

Parameters:: state (collections.abc.Mapping[str, Any])
Return type:: None

class sequince.steps.persistent.PersistentTemperedWeighting(target, *, beta, refresh_components=())[source]#

Bases: BasePersistentTemperedWeighting

Weight a persistent particle pool directly toward a fixed beta.

Parameters:

target (sequince.target.TemperedTarget)
beta (sequince.typing.ArrayLike)
refresh_components (collections.abc.Collection[str])

apply(state, context, rng)[source]#

Parameters:

state (sequince.state.ParticleState)
context (sequince.steps.context.StepContext)
rng (orng.RandomGenerator)

Return type:

tuple[sequince.state.PersistentParticleState, sequince.steps.context.StepContext, dict[str, Any]]

class sequince.steps.persistent.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=())[source]#

Bases: 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.

Parameters:

target (sequince.target.TemperedTarget) – Tempered target defining the persistent importance weights.
target_ess (float) – Desired effective sample size while selecting betas below 1.
target_total_ess (float | None) – Optional effective sample size required before stopping at beta = 1. If omitted, stop when beta = 1 is first selected.
dynamic (bool, optional) – 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.
resample_at_end (bool, optional) – 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.
beta_tolerance (float) – Stop bisection once the beta bracket is no wider than this.
max_bisection_iter (int) – Maximum number of bisection iterations.
refresh_components (collections.abc.Collection[str]) – Cached target-evaluation components to refresh before weighting.