sequince.steps.constraints

Likelihood-constrained SMC steps and shell evidence bookkeeping.

Attributes

LikelihoodThresholdSchedule

Classes

NestedSamplingLevel	Diagnostics for a shell; prior volume is measured before discarding it.
LikelihoodConstrainedPrior	A static prior and likelihood with a context-dependent hard constraint.
FixedLikelihoodThresholdSchedule	Use a strictly increasing sequence of log-likelihood thresholds.
QuantileLikelihoodThresholdSchedule	Select an observed likelihood at the weighted quantile.
WorstParticleLikelihoodThresholdSchedule	Discard the lowest likelihood among particles with positive weight.
LikelihoodThresholdSelection	Select a threshold or finalize using an estimated remaining-evidence ratio.
ShellEvidenceStep	Integrate a disjoint likelihood shell and optionally retain its particles.
LikelihoodThresholdWeighting	Normalize survivor weights and accumulate constrained-prior mass.
LogPriorMassStoppingCriterion	Finalize the remaining shell when prior mass falls below the given limit.

Module Contents

sequince.steps.constraints.LikelihoodThresholdSchedule

class sequince.steps.constraints.NestedSamplingLevel

Diagnostics for a shell; prior volume is measured before discarding it.

output_key: ClassVar[str] = 'nested_sampling_level'

iteration: int

shell_lower_threshold: float

shell_upper_threshold: float | None

log_prior_volume: float

log_shell_expectation: float

log_evidence_increment: float

log_evidence: float

is_terminal: bool

n_surviving: int

survival_fraction: float

class sequince.steps.constraints.LikelihoodConstrainedPrior(log_prior_fn, log_likelihood_fn, *, inclusive=False)

Bases: sequince.target.Target

A static prior and likelihood with a context-dependent hard constraint.

Parameters:

• log_prior_fn (callable) – Return one log density per particle, accepting particles and optionally a context. The density functions must remain unchanged between levels; their cached values are reused when only the threshold changes.

• log_likelihood_fn (callable) – Return one log density per particle, accepting particles and optionally a context. The density functions must remain unchanged between levels; their cached values are reused when only the threshold changes.

• inclusive (bool, optional) – Retain likelihoods equal to the threshold as well as those above it.

inclusive = False

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.

Parameters:

context (sequince.steps.context.StepContext)

Return type:

collections.abc.Collection[str]

evaluate(particles, context, *, components=None, evaluation=None)

Evaluate or refresh named components of the target.

Parameters:

• particles (sequince.typing.Array)

• context (sequince.steps.context.StepContext)

• components (collections.abc.Collection[str] | None)

• evaluation (sequince.target.TargetEvaluation | None)

Return type:

sequince.target.TargetEvaluation

log_prob(particles, context, *, evaluation=None)

Return the current target log density.

Parameters:

• particles (sequince.typing.Array)

• context (sequince.steps.context.StepContext)

• evaluation (sequince.target.TargetEvaluation | None)

Return type:

sequince.typing.Array | float

class sequince.steps.constraints.FixedLikelihoodThresholdSchedule

Use a strictly increasing sequence of log-likelihood thresholds.

Exhaustion records all remaining mass as a terminal shell. Positive infinity is also an explicit terminal threshold.

thresholds: collections.abc.Sequence[float]

class sequince.steps.constraints.QuantileLikelihoodThresholdSchedule

Select an observed likelihood at the weighted quantile.

Equal likelihoods are discarded together with a strict constraint. This can remove more than the requested fraction on a plateau.

quantile: float = 0.5

class sequince.steps.constraints.WorstParticleLikelihoodThresholdSchedule

Bases: QuantileLikelihoodThresholdSchedule

Discard the lowest likelihood among particles with positive weight.

class sequince.steps.constraints.LikelihoodThresholdSelection(target, *, threshold_schedule=None, evidence_tolerance=None, log_likelihood_upper_bound=None)

Bases: sequince.steps.base.SMCStep

Select a threshold or finalize using an estimated remaining-evidence ratio.

Schedules must implement schedule(log_likelihoods, state, context) and return a float or scalar array. StopIteration finalizes the remaining shell in eager/uncompiled execution; other exceptions propagate. Compiled schedules must be pure, JAX traceable, and use positive infinity to finalize rather than raising data-dependent exceptions or converting arrays to host scalars. Fixed and weighted-quantile schedules support both paths.

evidence_tolerance compares the current estimate X * E[L] with the accumulated evidence. It is a stopping heuristic, not a rigorous bound on unobserved modes. Supply a known log_likelihood_upper_bound to use X * Lmax instead (X itself is estimated), or disable it for fixed-schedule experiments.

Parameters:

• target (LikelihoodConstrainedPrior)

• threshold_schedule (LikelihoodThresholdSchedule | None)

• evidence_tolerance (float | None)

• log_likelihood_upper_bound (float | None)

target

schedule

evidence_tolerance = None

log_likelihood_upper_bound = None

validate_functional_configuration(config, state)

Reject unsupported NS-SMC pipelines before functional initialization.

Parameters:

• config (sequince.smc.SMCConfig)

• state (sequince.state.ParticleState)

Return type:

None

initialize_functional_metadata(state, metadata)

Return metadata with fields required by apply_functional.

Parameters:

• state (sequince.state.ParticleState)

• metadata (collections.abc.Mapping[str, Any])

Return type:

collections.abc.Mapping[str, Any]

initialize_functional_state_and_context(state, context)

Return shape-complete inputs for apply_functional.

Steps whose functional output adds array leaves should initialize matching leaves here so one compiled signature can be reused from the first iteration onward.

Parameters:

• state (sequince.state.ParticleState)

• context (sequince.steps.context.StepContext)

Return type:

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

validate_functional_state_and_context(state, context)

Validate numerical values at initialization and iteration boundaries.

Parameters:

• state (sequince.state.ParticleState)

• context (sequince.steps.context.StepContext)

Return type:

None

apply_functional(state, context, random_state)

Apply a functional step to particle step.

This returns the updated state, context, next random state, and any additional outputs.

This method is intended for use in functional SMC iterations where the random state is explicitly threaded through the computation.

Parameters:

• state (sequince.state.ParticleState)

• context (sequince.steps.context.StepContext)

• random_state (Any)

Return type:

tuple[sequince.state.ParticleState, sequince.steps.context.StepContext, Any, None]

apply(state, context, rng)

Parameters:

• state (sequince.state.ParticleState)

• context (sequince.steps.context.StepContext)

• rng (orng.RandomGenerator)

Return type:

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

class sequince.steps.constraints.ShellEvidenceStep(target, *, store_shell_particles=True)

Bases: sequince.steps.base.SMCStep

Integrate a disjoint likelihood shell and optionally retain its particles.

Parameters:

• target (LikelihoodConstrainedPrior)

• store_shell_particles (bool)

target

store_shell_particles = True

apply_functional(state, context, random_state)

Apply a functional step to particle step.

This returns the updated state, context, next random state, and any additional outputs.

This method is intended for use in functional SMC iterations where the random state is explicitly threaded through the computation.

Parameters:

• state (sequince.state.ParticleState)

• context (sequince.steps.context.StepContext)

• random_state (Any)

Return type:

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

apply(state, context, rng)

Parameters:

• state (sequince.state.ParticleState)

• context (sequince.steps.context.StepContext)

• rng (orng.RandomGenerator)

Return type:

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

class sequince.steps.constraints.LikelihoodThresholdWeighting(target)

Bases: sequince.steps.base.SMCStep

Normalize survivor weights and accumulate constrained-prior mass.

Parameters:

target (LikelihoodConstrainedPrior)

target

apply_functional(state, context, random_state)

Apply a functional step to particle step.

This returns the updated state, context, next random state, and any additional outputs.

This method is intended for use in functional SMC iterations where the random state is explicitly threaded through the computation.

Parameters:

• state (sequince.state.ParticleState)

• context (sequince.steps.context.StepContext)

• random_state (Any)

Return type:

tuple[sequince.state.ParticleState, sequince.steps.context.StepContext, Any, None]

apply(state, context, rng)

Parameters:

• state (sequince.state.ParticleState)

• context (sequince.steps.context.StepContext)

• rng (orng.RandomGenerator)

Return type:

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

class sequince.steps.constraints.LogPriorMassStoppingCriterion(min_log_prior_volume, target, *, store_shell_particles=True)

Bases: sequince.steps.base.SMCStep

Finalize the remaining shell when prior mass falls below the given limit.

Unlike the original prototype, stopping includes the surviving particles’ evidence and posterior contributions before requesting an immediate stop.

Parameters:

• min_log_prior_volume (float)

• target (LikelihoodConstrainedPrior)

• store_shell_particles (bool)

minimum

shell

apply_functional(state, context, random_state)

Apply a functional step to particle step.

This returns the updated state, context, next random state, and any additional outputs.

This method is intended for use in functional SMC iterations where the random state is explicitly threaded through the computation.

Parameters:

• state (sequince.state.ParticleState)

• context (sequince.steps.context.StepContext)

• random_state (Any)

Return type:

tuple[sequince.state.ParticleState, sequince.steps.context.StepContext, Any, Any]

apply(state, context, rng)

Parameters:

• state (sequince.state.ParticleState)

• context (sequince.steps.context.StepContext)

• rng (orng.RandomGenerator)

Return type:

tuple[sequince.state.ParticleState, sequince.steps.context.StepContext, Any]