sequince.steps.weighting

sequince.steps.weighting#

Attributes#

IncrementFn

BetaSchedule

TargetESSRatio

logger

Classes#

IncrementalWeighting

Apply a complete sequential-target log-weight increment.

LogLikelihoodWeighting

Backward-compatible name for callable likelihood increments.

BaseTemperedStep

Base class for tempered weighting steps.

TemperedWeighting

Apply tempering by scaling log-weight increments with a beta schedule.

FixedTemperedWeighting

Apply fixed beta increments up to max_beta (default 1.0).

AdaptiveTemperedWeighting

Adaptively choose the next beta using an ESS-like target.

Functions#

evolving_target_ess_ratio(start, end, *[, rate, max_beta])

Return a power-law schedule for an evolving target ESS ratio.

Module Contents#

sequince.steps.weighting.IncrementFn#
sequince.steps.weighting.BetaSchedule#
sequince.steps.weighting.TargetESSRatio#
sequince.steps.weighting.logger#
sequince.steps.weighting.evolving_target_ess_ratio(start, end, *, rate=1.0, max_beta=1.0)[source]#

Return a power-law schedule for an evolving target ESS ratio.

The schedule evolves from start to end as the beta moves from zero to max_beta. Betas outside that interval are clipped to the corresponding endpoint. Values of rate greater than one delay the transition, while values below one accelerate it.

Parameters:

  • start (float) – Target ESS ratio at zero beta; must be in (0, 1].

  • end (float) – Target ESS ratio at max_beta; must be in (0, 1].

  • rate (float) – Positive exponent controlling the rate of transition.

  • max_beta (float) – Positive beta at which the schedule reaches end.

Return type:

Callable[[float], float]

class sequince.steps.weighting.IncrementalWeighting(log_increment_fn, *, normalize_after=True)[source]#

Bases: sequince.steps.base.SMCStep

Apply a complete sequential-target log-weight increment.

A callable can have signature (particles,) or (particles, context). A SequentialTarget supplies its current complete increment and participates in evaluation caching.

Parameters:
initialize_functional_state_and_context(state, context)[source]#

Attach a cached target evaluation before functional compilation.

Parameters:
Return type:

tuple[sequince.state.ParticleState, sequince.steps.base.StepContext]

apply(state, context, rng)[source]#
Parameters:
Return type:

tuple[sequince.state.ParticleState, sequince.steps.base.StepContext, dict[str, Any]]

class sequince.steps.weighting.LogLikelihoodWeighting(log_increment_fn, *, normalize_after=True)[source]#

Bases: IncrementalWeighting

Backward-compatible name for callable likelihood increments.

Parameters:
class sequince.steps.weighting.BaseTemperedStep(log_increment_fn, *, normalize_after=True, refresh_components=())[source]#

Bases: sequince.steps.base.SMCStep

Base class for tempered weighting steps.

This provides common functionality for tempering steps that apply log-weight increments scaled by a beta schedule (e.g. TemperedWeighting and AdaptiveTemperedWeighting). It does not implement the logic for determining the beta schedule itself, which is left to subclasses.

Parameters:
initialize_functional_state_and_context(state, context)[source]#

Attach a cached target evaluation before functional compilation.

Parameters:
Return type:

tuple[sequince.state.ParticleState, sequince.steps.base.StepContext]

evaluate_log_increment(state, context)[source]#

Return increments and attach a missing target evaluation.

Parameters:
Return type:

tuple[sequince.typing.Array | float, sequince.state.ParticleState, sequince.steps.base.StepContext]

initialize_metadata(state, context)[source]#

Initialize metadata related to tempering.

Parameters:
Return type:

tuple[sequince.state.ParticleState, sequince.steps.base.StepContext]

initialize_functional_metadata(state, metadata)[source]#

Initialize fixed-shape tempering metadata on the array backend.

Parameters:
Return type:

collections.abc.Mapping[str, Any]

abstractmethod apply(state, context, rng)[source]#
class sequince.steps.weighting.TemperedWeighting(log_increment_fn, beta_schedule, *, normalize_after=True, clip_beta=None, refresh_components=())[source]#

Bases: BaseTemperedStep

Apply tempering by scaling log-weight increments with a beta schedule.

Both the increment callable and the beta schedule accept the current StepContext when they require it.

Parameters:
apply(state, context, rng)[source]#
Parameters:
Return type:

tuple[sequince.state.ParticleState, sequince.steps.base.StepContext, dict[str, Any]]

class sequince.steps.weighting.FixedTemperedWeighting(log_increment_fn, *, beta_increment, max_beta=1.0, normalize_after=True, refresh_components=())[source]#

Bases: BaseTemperedStep

Apply fixed beta increments up to max_beta (default 1.0).

Clip the final increment and request a stop after that iteration. The maximum must be finite and positive.

Parameters:
apply(state, context, rng)[source]#
Parameters:
Return type:

tuple[sequince.state.ParticleState, sequince.steps.base.StepContext, dict[str, Any]]

apply_functional(state, context, random_state)[source]#

Apply fixed tempering without host scalar conversions.

Parameters:
Return type:

tuple[sequince.state.ParticleState, sequince.steps.base.StepContext, Any, dict[str, Any]]

class sequince.steps.weighting.AdaptiveTemperedWeighting(log_increment_fn, *, target_ess_ratio=0.7, max_beta=1.0, min_delta=0.0001, max_delta=None, normalize_after=True, max_bisection_iter=30, criterion='ess', refresh_components=())[source]#

Bases: BaseTemperedStep

Adaptively choose the next beta using an ESS-like target.

The beta increment is chosen such that the effective sample size (ESS) ratio after weighting, or the conditional ESS (CESS) ratio implied by a proposed increment, reaches the specified target value (target_ess_ratio), up to the maximum beta (max_beta). If the maximum beta is reached while advancing the schedule, the SMC run is requested to stop after the current iteration finishes.

Parameters:

  • log_increment_fn (IncrementFn | sequince.target.TemperedTarget) – A callable or TemperedTarget providing log-weight increments.

  • target_ess_ratio (TargetESSRatio) – The target ESS ratio (ESS / n) to achieve after weighting, or a callable that returns the target for the current beta. The callable may optionally also accept the current StepContext. Each resolved target must be in the interval (0, 1].

  • max_beta (float) – The maximum beta to reach; once this beta is reached, the SMC run is requested to stop after the current iteration.

  • min_delta (float) – The minimum beta increment to apply at each step.

  • max_delta (float | None) – Optional maximum beta increment to apply at each step.

  • normalize_after (bool) – Whether to normalize the particle weights after updating.

  • max_bisection_iter (int) – The maximum number of bisection iterations to perform when finding the beta increment.

  • criterion (Literal['ess', 'cess']) – Criterion used when selecting the beta increment. "ess" targets the ESS ratio after weighting. "cess" targets the conditional ESS ratio induced by the proposed incremental weights.

  • refresh_components (collections.abc.Collection[str])

Notes

The returned particle state and current step context record beta, delta_beta, ess_ratio, and cess_ratio. Active updates also record target_ess_ratio.

initialize_functional_metadata(state, metadata)[source]#

Initialize fixed-shape adaptive tempering metadata.

Parameters:
Return type:

collections.abc.Mapping[str, Any]

apply(state, context, rng)[source]#
Parameters:
Return type:

tuple[sequince.state.ParticleState, sequince.steps.base.StepContext, dict[str, Any]]

apply_functional(state, context, random_state)[source]#

Apply adaptive tempering while explicitly threading random state.

Parameters:
Return type:

tuple[sequince.state.ParticleState, sequince.steps.base.StepContext, Any, dict[str, Any]]