sequince.steps.mutation.repeated#

Complete mutation blocks with explicit rounds and metric ownership.

Classes#

RepeatedMutationStepOutput

Mutation and post-round outputs plus one complete diagnostic record.

RepeatedMutationStep

Run fixed mutation rounds with one shared collection of metric states.

Module Contents#

class sequince.steps.mutation.repeated.RepeatedMutationStepOutput[source]#

Mutation and post-round outputs plus one complete diagnostic record.

round_outputs: tuple[Any, ...]#
after_round_outputs: tuple[Any, ...]#
metrics: sequince.steps.mutation.metrics.MutationMetricsOutput | None#
class sequince.steps.mutation.repeated.RepeatedMutationStep(mutation, *, n_rounds=1, n_steps=None, after_round=None)[source]#

Bases: sequince.steps.base.SMCStep

Run fixed mutation rounds with one shared collection of metric states.

n_steps is the total default budget. If omitted, use the child’s configured length times n_rounds. apply_with_n_steps overrides the total for a single call. Budgets are divided evenly, with the remainder assigned to the first rounds.

after_round is an ordinary SMCStep, executed after every round, including zero-step rounds and the final round. It never receives metric state. The mutation refreshes references on entering the following round without recording the intervening displacement or changing frozen scaling.

Metrics are configured on the mutation child. Runtime state is local to the block call and passed explicitly through the rounds. Nested blocks share the same state and only the outermost block finalizes metrics. Fixed schedules execute all rounds even if a child requests stopping; the stop flags remain available to the enclosing SMC runner.

Parameters:
n_rounds = 1#
mutation#
after_round = None#
property n_steps: int#

Default total number of transitions across all rounds.

Return type:

int

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

Static metric configuration owned by the mutation child.

Return type:

sequince.steps.mutation.metrics.MutationMetrics

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

n_steps (int)

apply_with_mutation_state(state, context, rng, *, n_steps, mutation_state=None)[source]#

Run all rounds and return mutation state without finalizing it.

None starts a new block. An existing state continues an enclosing block, preserving its metric scaling and cumulative bookkeeping.

Parameters:
Return type:

tuple[sequince.state.ParticleState, sequince.steps.context.StepContext, RepeatedMutationStepOutput, sequince.steps.mutation.metrics.MutationStepState | None]

validate_functional_configuration(config, state, *, max_steps=None)[source]#

Validate each child once with its effective per-round capacity.

Parameters:
Return type:

None

initialize_functional_metadata(state, metadata)[source]#

Return metadata with fields required by apply_functional.

Parameters:
Return type:

collections.abc.Mapping[str, 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]

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

Split a runtime total by quotient/remainder and share metric state.

Round capacities use the same split of max_steps, so their sum is exactly max_steps. Each round exposes its own executed count. Post-round steps run even for zero-budget rounds.

Parameters:
Return type:

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

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