sequince.steps.base#
Classes#
Capability for mutation-like steps accepting a per-call transition count. |
|
Functional mutation with a runtime budget and static history capacity. |
|
Base class for steps with explicit context and output returns. |
Functions#
|
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.
- class sequince.steps.base.FixedLengthMutation[source]#
Bases:
ProtocolCapability for mutation-like steps accepting a per-call transition count.
n_stepsis 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:
state (sequince.state.ParticleState)
context (sequince.steps.context.StepContext)
rng (Any)
n_steps (int)
- Return type:
tuple[sequince.state.ParticleState, sequince.steps.context.StepContext, Any]
- class sequince.steps.base.DynamicBudgetMutation[source]#
Bases:
ProtocolFunctional 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_stateis the backend-native state returned byorng.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 optionalmax_stepsoverride 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:
state (sequince.state.ParticleState)
metadata (collections.abc.Mapping[str, Any])
- Return type:
collections.abc.Mapping[str, Any]
- initialize_functional_state_and_context(state, context)[source]#
- Parameters:
state (sequince.state.ParticleState)
context (sequince.steps.context.StepContext)
- Return type:
tuple[sequince.state.ParticleState, sequince.steps.context.StepContext]
- validate_functional_configuration(config, state, *, max_steps=None)[source]#
- Parameters:
config (sequince.smc.SMCConfig)
state (sequince.state.ParticleState)
max_steps (int | None)
- Return type:
None
- apply_dynamic_budget(state, context, random_state, *, n_steps, max_steps, mutation_state=None)[source]#
- Parameters:
state (sequince.state.ParticleState)
context (sequince.steps.context.StepContext)
random_state (Any)
n_steps (sequince.typing.Array)
max_steps (int)
mutation_state (sequince.steps.mutation.metrics.MutationStepState | None)
- 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:
state (sequince.state.ParticleState)
context (sequince.steps.context.StepContext)
rng (orng.RandomGenerator)
- 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:
state (sequince.state.ParticleState)
context (sequince.steps.context.StepContext)
random_state (Any)
- 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:
state (sequince.state.ParticleState)
metadata (collections.abc.Mapping[str, Any])
- 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:
state (sequince.state.ParticleState)
context (sequince.steps.context.StepContext)
- Return type:
tuple[sequince.state.ParticleState, sequince.steps.context.StepContext]
- load_state_dict(state)[source]#
Restore state produced by
state_dict().- Parameters:
state (collections.abc.Mapping[str, Any])
- Return type:
None