Core modules

Core modules#

Top-level API#

Sequential Monte Carlo driver#

Reconstruct a runner with SequentialMonteCarlo.from_config(smc.config). This preserves runner settings and shares the referenced steps, callbacks, and checkpoint writers. It does not clone mutable component state or resume a run; use the checkpoint APIs to restore runtime state.

Particle state and results#

class sequince.state.ParticleState(particles, log_weights=None, log_normalizing_constant=0.0, initial_ancestor_indices=None, evaluation=None, metadata=None)[source]#

Bases: object

Container for particle locations, log weights, and auxiliary information.

log_normalizing_constant is the accumulated estimate of log Z for the SMC target sequence. For Bayesian posterior SMC this is the log evidence; for particle filtering it is the log marginal likelihood of the observation sequence.

Parameters:

  • particles (Array)

  • log_weights (Array | Real | None)

  • log_normalizing_constant (float)

  • initial_ancestor_indices (Array | None)

  • evaluation (TargetEvaluation | None)

  • metadata (MutableMapping[str, Any] | None)

copy()[source]#

Return a copy of the state preserving the array backend.

Return type:

ParticleState

effective_sample_size()[source]#

Compute the effective sample size (ESS).

Return type:

float

encode_for_hdf5()[source]#

Return a versioned, portable particle-state payload.

Return type:

dict[str, Any]

evaluation: TargetEvaluation | None = None#
classmethod from_dict(payload)[source]#

Reconstruct a state from to_dict() output.

Parameters:

payload (Mapping[str, Any])

Return type:

ParticleState

initial_ancestor_indices: Array#
classmethod load(h5_file_or_group, path='state')[source]#

Load a built-in state from path in an open HDF5 handle.

Parameters:

  • h5_file_or_group (Any)

  • path (str)

Return type:

Self

property log_evidence: float#

Alias for log_normalizing_constant.

log_normalizing_constant: float = 0.0#
log_weights: Array#
metadata: MutableMapping[str, Any]#
normalize()[source]#

Return a new state and its incremental log normalizing constant.

Return type:

tuple[ParticleState, float]

particles: Array#
replace_particles(particles, *, evaluation=None, **updates)[source]#

Replace particles and explicitly provide their evaluation.

Parameters:

  • particles (Array)

  • evaluation (TargetEvaluation | None)

  • updates (Any)

Return type:

ParticleState

resample(indices)[source]#

Return a resampled state using the provided ancestor indices.

Parameters:

indices (Any)

Return type:

ParticleState

save(h5_file_or_group, path='state')[source]#

Save this state below path in an open HDF5 handle.

Parameters:

  • h5_file_or_group (Any)

  • path (str)

Return type:

None

to_dict()[source]#

Return a detached dictionary representation of this state.

Return type:

dict[str, Any]

property weights: Any#

Return normalized weights.

with_updates(**kwargs)[source]#

Return a copy of the state with selective updates applied.

Parameters:

kwargs (Any)

Return type:

ParticleState

class sequince.state.PersistentParticleState(particles, betas, log_normalizing_constants, batch_size, *, log_weights=None, log_normalizing_constant=None, initial_ancestor_indices=None, evaluation=None, metadata=None)[source]#

Bases: ParticleState

Equal-sized particle batches retained from historical targets.

log_normalizing_constants contains normalizing-constant estimates for targets which generated archived batches. The scalar log_normalizing_constant follows the ordinary ParticleState interface and may instead describe a new target toward which the archive has just been weighted.

Parameters:

  • particles (Array)

  • betas (ArrayLike)

  • log_normalizing_constants (ArrayLike)

  • batch_size (int)

  • log_weights (Array | None)

  • log_normalizing_constant (Any | None)

  • initial_ancestor_indices (Array | None)

  • evaluation (TargetEvaluation | None)

  • metadata (MutableMapping[str, Any] | None)

append(state, *, beta, log_normalizing_constant)[source]#

Return a new history with one equal-sized batch appended.

Ancestor indices are concatenated without offsets because every batch retains its genealogy relative to the same initial active population.

Parameters:
Return type:

PersistentParticleState

batch_size: int#
betas: Array#
copy()[source]#

Return an independent copy preserving the persistent structure.

Return type:

PersistentParticleState

encode_for_hdf5()[source]#

Return a versioned payload including persistent history.

Return type:

dict[str, Any]

classmethod from_dict(payload)[source]#

Reconstruct a persistent state from to_dict() output.

Parameters:

payload (Mapping[str, Any])

Return type:

PersistentParticleState

classmethod from_state(state, *, beta, log_normalizing_constant)[source]#

Create a one-batch history from an active particle state.

Parameters:
Return type:

PersistentParticleState

property log_evidence: float#

Alias for log_normalizing_constant.

property log_evidences: Any#

Alias for log_normalizing_constants.

log_normalizing_constants: Array#
property n_batches: int#

Return the number of historical particle batches.

property n_particles: int#

Return the total number of retained particles.

to_dict()[source]#

Return a detached dictionary including persistent history.

Return type:

dict[str, Any]

with_updates(**kwargs)[source]#

Return a copy with non-structural fields updated.

Historical particles and their batch metadata can only change through append(). Persistent weighting steps may update log_weights; callers may also replace compatible evaluations or metadata.

Parameters:

kwargs (Any)

Return type:

PersistentParticleState

sequince.state.normalize_log_weights(log_weights, *, xp=None)[source]#

Return normalized log weights and their array scalar normalizer.

Parameters:

  • log_weights (Any)

  • xp (Any | None)

Checkpointing#

Posterior utilities#

Pre-built samplers#