sequince.steps.control

sequince.steps.control#

Attributes#

logger

Classes#

ConditionalStepOutput

Output from a step that may skip its child.

ContinueWhile

Ensure the SMC loop continues while a predicate holds.

StopIf

Request the SMC loop to stop when a predicate holds.

PeriodicStep

Apply a step every N iterations.

RepeatStep

Repeat a step or sequence of steps a fixed number of times.

SequentialStep

Apply several SMC steps in order.

Functions#

apply_functional_if(predicate, apply, state, context, ...)

Conditionally execute a functional step through backend control flow.

Module Contents#

sequince.steps.control.logger#
sequince.steps.control.apply_functional_if(predicate, apply, state, context, random_state)[source]#

Conditionally execute a functional step through backend control flow.

Parameters:

  • predicate (bool or scalar array) – Execute the step when true; otherwise preserve the entire input carry.

  • apply (callable) – Pure, traceable apply(state, context, random_state) operation.

  • state (ParticleState) – Initialized particle state, including any evaluation cache.

  • context (StepContext) – Initialized context with all metadata required by the operation.

  • random_state (object) – Explicit backend random state.

Returns:

state, context, random_state, output – Executed step results, or unchanged inputs. Skipped output is None on eager backends. On JAX it contains zero array placeholders in the step’s output structure, with static fields unchanged.

Return type:

tuple

Notes

Uses acai.cond: eager backends execute only the selected branch. On JAX, abstract evaluation traces apply even when skipped, but does not execute transitions or consume random draws. Both branches must preserve the carry’s pytree structure, shapes, and dtypes. Initialize missing leaves with the functional initialization hooks before calling this helper. Output leaves must support JAX zero construction; placeholders are not step diagnostics. PyTorch execution is eager; structured torch.compile is not guaranteed.

class sequince.steps.control.ConditionalStepOutput[source]#

Output from a step that may skip its child.

executed: bool#
child_output: Any = None#
class sequince.steps.control.ContinueWhile(predicate)[source]#

Bases: sequince.steps.base.SMCStep

Ensure the SMC loop continues while a predicate holds.

This step clears any stop requests raised by earlier steps when the supplied predicate evaluates to True for the current ParticleState and StepContext. When the predicate returns False the stop flags remain untouched, allowing the run to terminate.

Parameters:

predicate (Callable[[sequince.state.ParticleState, sequince.steps.base.StepContext], bool]) – A callable receiving the current ParticleState and StepContext and returning a boolean indicating whether to continue the SMC loop.

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

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

class sequince.steps.control.StopIf(predicate, *, immediate=False)[source]#

Bases: sequince.steps.base.SMCStep

Request the SMC loop to stop when a predicate holds.

This step sets a stop request flag in the context when the supplied predicate evaluates to True for the current ParticleState and StepContext. When the predicate returns False the stop flag remains untouched, allowing the run to continue.

Parameters:

  • predicate (Callable[[sequince.state.ParticleState, sequince.steps.base.StepContext], bool]) – A callable receiving the current ParticleState and StepContext and returning a boolean indicating whether to request stopping the SMC loop.

  • immediate (bool) – When True, halt the current iteration immediately. When False, stop after the current iteration finishes.

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

Evaluate a traceable predicate without consuming random state.

Parameters:
Return type:

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

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

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

class sequince.steps.control.PeriodicStep(step, n, offset=0)[source]#

Bases: sequince.steps.base.SMCStep

Apply a step every N iterations.

This step applies the supplied step only on iterations where the current iteration number is a multiple of n. On other iterations, it simply returns the input state unchanged.

Parameters:

  • step (sequince.steps.base.SMCStep) – The step to apply every N iterations.

  • n (int) – The number of iterations between applications of the step.

  • offset (int) – An optional offset to apply to the iteration number before checking for divisibility. This allows you to, for example, apply a step every 5 iterations starting from iteration 2 by setting n=5 and offset=2.

step#
n#
offset = 0#
apply(state, context, rng)[source]#
Parameters:
Return type:

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

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

class sequince.steps.control.RepeatStep(step, n)[source]#

Bases: sequince.steps.base.SMCStep

Repeat a step or sequence of steps a fixed number of times.

Parameters:
step#
n#
apply(state, context, rng)[source]#
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

class sequince.steps.control.SequentialStep(steps)[source]#

Bases: sequince.steps.base.SMCStep

Apply several SMC steps in order.

This is useful for grouping multiple steps together into a single step, which can then be used in other contexts (e.g., as part of a RepeatStep or PeriodicStep).

Parameters:

steps (Sequence[sequince.steps.base.SMCStep])

steps#
apply(state, context, rng)[source]#
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