sequince.state

Classes

ParticleState	Container for particle locations, log weights, and auxiliary information.
PersistentParticleState	Equal-sized particle batches retained from historical targets.

Functions

normalize_log_weights(log_weights, *[, xp])

Return normalized log weights and their array scalar normalizer.

Module Contents

sequince.state.normalize_log_weights(log_weights, *, xp=None)

Return normalized log weights and their array scalar normalizer.

Parameters:

• log_weights (Any)

• xp (Any | None)

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

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 (sequince.typing.Array)

• log_weights (sequince.typing.Array | numbers.Real | None)

• log_normalizing_constant (float)

• initial_ancestor_indices (sequince.typing.Array | None)

• evaluation (sequince.target.TargetEvaluation | None)

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

particles: sequince.typing.Array

log_weights: sequince.typing.Array

initial_ancestor_indices: sequince.typing.Array

log_normalizing_constant: float = 0.0

evaluation: sequince.target.TargetEvaluation | None = None

metadata: MutableMapping[str, Any]

property log_evidence: float

Alias for log_normalizing_constant.

Return type:

float

copy()

Return a copy of the state preserving the array backend.

Return type:

ParticleState

normalize()

Return a new state and its incremental log normalizing constant.

Return type:

tuple[ParticleState, float]

property weights: sequince.typing.Array

Return normalized weights.

Return type:

sequince.typing.Array

effective_sample_size()

Compute the effective sample size (ESS).

Return type:

float

with_updates(**kwargs)

Return a copy of the state with selective updates applied.

Parameters:

kwargs (Any)

Return type:

ParticleState

replace_particles(particles, *, evaluation=None, **updates)

Replace particles and explicitly provide their evaluation.

Parameters:

• particles (sequince.typing.Array)

• evaluation (sequince.target.TargetEvaluation | None)

• updates (Any)

Return type:

ParticleState

resample(indices)

Return a resampled state using the provided ancestor indices.

Parameters:

indices (sequince.typing.Array)

Return type:

ParticleState

to_dict()

Return a detached dictionary representation of this state.

Return type:

dict[str, Any]

classmethod from_dict(payload)

Reconstruct a state from to_dict() output.

Parameters:

payload (collections.abc.Mapping[str, Any])

Return type:

ParticleState

encode_for_hdf5()

Return a versioned, portable particle-state payload.

Return type:

dict[str, Any]

save(h5_file_or_group, path='state')

Save this state below path in an open HDF5 handle.

Parameters:

• h5_file_or_group (Any)

• path (str)

Return type:

None

classmethod load(h5_file_or_group, path='state')

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

Parameters:

• h5_file_or_group (Any)

• path (str)

Return type:

Self

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)

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 (sequince.typing.Array)

• betas (sequince.typing.ArrayLike)

• log_normalizing_constants (sequince.typing.ArrayLike)

• batch_size (int)

• log_weights (sequince.typing.Array | None)

• log_normalizing_constant (Any | None)

• initial_ancestor_indices (sequince.typing.Array | None)

• evaluation (sequince.target.TargetEvaluation | None)

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

betas: sequince.typing.Array

log_normalizing_constants: sequince.typing.Array

batch_size: int

property log_evidence: float

Alias for log_normalizing_constant.

Return type:

float

property log_evidences: sequince.typing.Array

Alias for log_normalizing_constants.

Return type:

sequince.typing.Array

property n_particles: int

Return the total number of retained particles.

Return type:

int

property n_batches: int

Return the number of historical particle batches.

Return type:

int

classmethod from_state(state, *, beta, log_normalizing_constant)

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

Parameters:

• state (ParticleState)

• beta (sequince.typing.ArrayLike)

• log_normalizing_constant (sequince.typing.ArrayLike)

Return type:

PersistentParticleState

copy()

Return an independent copy preserving the persistent structure.

Return type:

PersistentParticleState

with_updates(**kwargs)

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

append(state, *, beta, log_normalizing_constant)

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:

• state (ParticleState)

• beta (sequince.typing.ArrayLike)

• log_normalizing_constant (sequince.typing.ArrayLike)

Return type:

PersistentParticleState

to_dict()

Return a detached dictionary including persistent history.

Return type:

dict[str, Any]

classmethod from_dict(payload)

Reconstruct a persistent state from to_dict() output.

Parameters:

payload (collections.abc.Mapping[str, Any])

Return type:

PersistentParticleState

encode_for_hdf5()

Return a versioned payload including persistent history.

Return type:

dict[str, Any]