sequince.smc

sequince.smc#

Attributes#

logger

IterationCallable

StepCallable

Classes#

SMCConfig

Read-only snapshot of runner settings, separate from runtime state.

SMCRuntime

Prepared SMC runtime state for fresh or resumed execution.

SequentialMonteCarlo

Composable Sequential Monte Carlo runner.

Module Contents#

sequince.smc.logger#
type sequince.smc.IterationCallable = Callable[[ParticleState, StepContext, Any], tuple[ParticleState, StepContext, Any, tuple[Any, ...]]]#
type sequince.smc.StepCallable = Callable[[ParticleState, StepContext, 'RandomGenerator'], tuple[ParticleState, StepContext, Any]]#
class sequince.smc.SMCConfig[source]#

Read-only snapshot of runner settings, separate from runtime state.

Variables:

  • steps (tuple of callables) – Ordered pipeline. Step objects retain their identity and mutable state.

  • callbacks (tuple of callables) – Host callbacks invoked after each iteration.

  • checkpoint_writers (tuple of CheckpointWriter) – Writers invoked at checkpoint boundaries.

  • auto_normalize (bool) – Whether the runner normalizes weights after each iteration.

Notes

Containers and fields are immutable; referenced steps, callbacks, and writers are not copied or frozen. This is a host-side configuration view, not a checkpoint payload or compiled carry.

steps: tuple[StepCallable, ...]#
callbacks: tuple[Callable[..., sequince.steps.base.StepContext | None], ...]#
checkpoint_writers: tuple[sequince.checkpoint.CheckpointWriter, ...]#
auto_normalize: bool#
class sequince.smc.SMCRuntime[source]#

Prepared SMC runtime state for fresh or resumed execution.

rng contains either an orng.RandomGenerator for eager execution or an explicit backend random state for functional execution.

state: sequince.state.ParticleState#
produced_states: list[sequince.state.ParticleState]#
initial_state: sequince.state.ParticleState | None#
t: int#
next_observation_index: int#
shared_context: collections.abc.Mapping[str, Any]#
metadata: collections.abc.Mapping[str, Any]#
evaluation_counts: sequince.target.EvaluationCounts#
outputs: list[tuple[Any, ...]]#
rng: Any#
class sequince.smc.SequentialMonteCarlo(steps, *, callbacks=None, checkpoint_writers=None, auto_normalize=True)[source]#

Composable Sequential Monte Carlo runner.

Users supply an ordered collection of SMC steps that will be called in sequence at each iteration. Steps return the updated particle state, context, and an explicit output describing the completed work.

Parameters:

  • steps (collections.abc.Sequence[StepCallable]) – A sequence of callables implementing SMC steps. Each callable should accept the current ParticleState, current StepContext, and an orng.RandomGenerator, and return (state, context, output).

  • callbacks (collections.abc.Sequence[Callable[..., sequince.steps.base.StepContext | None]] | None) – Optional callbacks invoked after each completed iteration with the current state, context, and partial SMCResult. A callback may return an updated context, or None when observational.

  • checkpoint_writers (collections.abc.Sequence[sequince.checkpoint.CheckpointWriter] | None) – Optional persistence hooks invoked with a committed checkpoint after callbacks have completed.

  • auto_normalize (bool) – If True, normalize particle weights after each iteration.

property config: SMCConfig#

Return a read-only snapshot of the current runner settings.

Return type:

SMCConfig

classmethod from_config(config)[source]#

Construct a runner from a configuration snapshot.

Parameters:

config (SMCConfig) – Runner settings, such as those returned by runner.config.

Returns:

A new runner constructed through cls with the supplied settings.

Return type:

SequentialMonteCarlo

Notes

Steps, callbacks, and checkpoint writers are shared by reference. This does not clone their mutable state or restore a checkpoint. Subclasses must accept the same constructor arguments.

state_dict()[source]#

Return mutable state for the configured step pipeline.

Return type:

dict[str, Any]

load_state_dict(state)[source]#

Restore mutable state for the configured step pipeline.

Parameters:

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

Return type:

None

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

Apply one eager SMC iteration.

The returned RNG is the same mutable generator supplied by the caller. Returning it gives eager and functional iterations a common internal calling convention.

Parameters:
Return type:

tuple[sequince.state.ParticleState, sequince.steps.base.StepContext, orng.RandomGenerator, tuple[Any, …]]

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

Apply one pure, explicitly RNG-threaded SMC iteration.

Notes

After each step, context.stop_immediately guards subsequent steps, preserving terminal particles and RNG state. Guarded JAX steps require initialized carries with matching structures, shapes, and dtypes. Ordinary stop requests are handled after the complete iteration. Skipped JAX outputs contain zero placeholders with their usual structure; eager backend skips return None as the step output.

Parameters:
Return type:

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

run(initial_state=None, observations=None, num_steps=None, rng=None, shared_context=None, metadata=None, outputs=None, runtime=None)[source]#

Run the SMC algorithm using a mutable random generator.

Parameters:
Return type:

sequince.result.SMCResult

initialize_functional(initial_state, context)[source]#

Return shape-complete state and context for functional execution.

Parameters:
Return type:

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

run_functional(initial_state=None, observations=None, num_steps=None, random_state=None, shared_context=None, metadata=None, outputs=None, runtime=None, iteration=None)[source]#

Run the SMC algorithm with explicit random-state threading.

iteration may be an externally transformed version of functional_iteration(), for example jax.jit(smc.functional_iteration).

Returns:

  • result (SMCResult) – The completed SMC result.

  • random_state (object) – The final backend-native random state.

Parameters:
Return type:

tuple[sequince.result.SMCResult, Any]

resume_from(checkpoint, *, rng=None, shared_context=None)[source]#

Reconstruct eager runtime state from a checkpoint.

Parameters:
Return type:

SMCRuntime

resume_functional_from(checkpoint, *, random_state=None, shared_context=None)[source]#

Reconstruct functional runtime state from a checkpoint.

Parameters:
Return type:

SMCRuntime