sequince.steps.base#

Classes#

FixedLengthMutation

Capability for mutation-like steps accepting a per-call transition count.

DynamicBudgetMutation

Functional mutation with a runtime budget and static history capacity.

SMCStep

Base class for steps with explicit context and output returns.

Functions#

validate_n_steps(n_steps)

Validate a caller-supplied fixed mutation length.

Module Contents#

sequince.steps.base.validate_n_steps(n_steps)[source]#

Validate a caller-supplied fixed mutation length.

Parameters:

n_steps (int)

Return type:

int

class sequince.steps.base.FixedLengthMutation[source]#

Bases: Protocol

Capability for mutation-like steps accepting a per-call transition count.

n_steps is a host-side integer. Backends such as JAX therefore require it to be static while tracing or compiling a call.

apply_with_n_steps(state, context, rng, *, n_steps)[source]#
Parameters:
Return type:

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

class sequince.steps.base.DynamicBudgetMutation[source]#

Bases: Protocol

Functional mutation with a runtime budget and static history capacity.

The scalar integer array budget must lie in [0, max_steps]. Initialize the functional state/context and metadata before tracing. The returned metric state continues an enclosing block; only its owner finalizes metrics. random_state is the backend-native state returned by orng.RandomGenerator.state(); for JAX it is a PRNG key array. Functional calls accept and return that state, while eager methods accept the ORNG generator object. Configuration validation accepts an optional max_steps override so enclosing adapters validate the effective history capacity rather than the child’s default sweep count.

property metrics: sequince.steps.mutation.metrics.MutationMetrics#
Return type:

sequince.steps.mutation.metrics.MutationMetrics

initialize_functional_metadata(state, metadata)[source]#
Parameters:
Return type:

collections.abc.Mapping[str, Any]

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

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

validate_functional_configuration(config, state, *, max_steps=None)[source]#
Parameters:
Return type:

None

apply_dynamic_budget(state, context, random_state, *, n_steps, max_steps, mutation_state=None)[source]#
Parameters:
Return type:

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

class sequince.steps.base.SMCStep[source]#

Base class for steps with explicit context and output returns.

Functional steps request immediate stopping through StepContext. The runner conditionally skips later steps, which must have initialized, fixed-structure functional carries under JAX.

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

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

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

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. Pass the backend-native state returned by orng.RandomGenerator.state(); for JAX this is a PRNG key array. An ORNG wrapper is reconstructed internally, and its advanced state is returned to the caller.

Parameters:
Return type:

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

validate_functional_configuration(config, state)[source]#

Validate host-side pipeline settings before initializing any step.

Parameters:
  • config (SMCConfig) – Read-only runner configuration, including the complete pipeline.

  • state (ParticleState) – Initial particle state, including the population shape.

Return type:

None

Notes

Override to reject incompatible pipeline settings. Metadata and cache preparation belong in the existing functional initialization hooks.

initialize_functional_metadata(state, metadata)[source]#

Return metadata with fields required by apply_functional.

Parameters:
Return type:

collections.abc.Mapping[str, Any]

initialize_functional_state_and_context(state, context)[source]#

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:
Return type:

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

state_dict()[source]#

Return mutable state required by subsequent SMC iterations.

Return type:

dict[str, Any]

load_state_dict(state)[source]#

Restore state produced by state_dict().

Parameters:

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

Return type:

None