sequince.steps.mutation.metropolis#

Attributes#

Classes#

MetropolisHastingsMutation

Rejuvenate particles with a custom Metropolis-Hastings kernel.

RedBlueMetropolisHastingsMutation

Metropolis-Hastings updates using complementary particle ensembles.

DifferentialEvolutionMutation

Rejuvenate particles with red-blue differential-evolution proposals.

Module Contents#

sequince.steps.mutation.metropolis.logger#
sequince.steps.mutation.metropolis.MutationKernelFactory#
class sequince.steps.mutation.metropolis.MetropolisHastingsMutation(log_prob_fn, kernel, *, n_steps=1, transform=None, transform_refit='always', store_chains=False, metrics=())[source]#

Bases: sequince.steps.mutation.base.MutationStep

Rejuvenate particles with a custom Metropolis-Hastings kernel.

The kernel operates on the complete particle array, allowing both independent and ensemble proposals. All numerical operations remain in the input array namespace.

Parameters:
  • log_prob_fn (Callable[..., sequince.typing.Array | float] | sequince.target.Target)

  • kernel (sequince.steps.mutation.kernels.MutationKernel | MutationKernelFactory)

  • n_steps (int)

  • transform (sequince.transforms.ParticleTransform | None)

  • transform_refit (sequince.steps.mutation.base.TransformRefit)

  • store_chains (bool)

  • metrics (tuple[sequince.steps.mutation.metrics.MutationMetric, ...] | list[sequince.steps.mutation.metrics.MutationMetric])

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

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

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

Run transitions within a block without finalizing metrics.

Pass mutation_state=None to initialize a new block; otherwise pass the state returned by the preceding call. The state holds individual metric states and cumulative acceptance bookkeeping. It must belong to the same metric configuration and mutation coordinate space.

Returns (state, context, output, mutation_state). The output’s metrics remain unset, including on the first and zero-step calls. Concrete mutations prepare existing metrics on entry, update state for each transition, and return it explicitly without calling metric.result(). Runtime state must never be stored on the mutation object.

Use apply or apply_with_n_steps for a complete standalone block. RepeatedMutationStep uses this method to continue across rounds and finalizes metrics once after the complete block.

Parameters:
Return type:

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

class sequince.steps.mutation.metropolis.RedBlueMetropolisHastingsMutation(log_prob_fn, kernel, *, n_steps=1, transform=None, transform_refit='always', store_chains=False, metrics=())[source]#

Bases: MetropolisHastingsMutation

Metropolis-Hastings updates using complementary particle ensembles.

Each of n_steps is one complete red-blue sweep. The population is randomly repartitioned, the red group is updated against the frozen blue group, and then blue is updated against the accepted red population. A persistent ComplementaryEnsembleKernel receives both groups directly. DE scale diagnostics are opt-in: configure DEScaleMetrics with the kernel’s scale_multipliers in metrics, or use AdaptDEScaleWeights, which configures the required metric once.

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

Initialize acceptance metadata before tracing red-blue updates.

Parameters:
Return type:

collections.abc.Mapping[str, Any]

property kernel: sequince.steps.mutation.kernels.ComplementaryEnsembleKernel#

Fixed complementary kernel; replace between mutation calls.

Return type:

sequince.steps.mutation.kernels.ComplementaryEnsembleKernel

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

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

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

Run transitions within a block without finalizing metrics.

Pass mutation_state=None to initialize a new block; otherwise pass the state returned by the preceding call. The state holds individual metric states and cumulative acceptance bookkeeping. It must belong to the same metric configuration and mutation coordinate space.

Returns (state, context, output, mutation_state). The output’s metrics remain unset, including on the first and zero-step calls. Concrete mutations prepare existing metrics on entry, update state for each transition, and return it explicitly without calling metric.result(). Runtime state must never be stored on the mutation object.

Use apply or apply_with_n_steps for a complete standalone block. RepeatedMutationStep uses this method to continue across rounds and finalizes metrics once after the complete block.

Parameters:
Return type:

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

class sequince.steps.mutation.metropolis.DifferentialEvolutionMutation(log_prob_fn, *, n_steps=1, gamma=None, gamma_one_probability=0.1, gamma_randomization='none', scale_multipliers=(1.0,), scale_weights=None, noise_scale=1e-05, transform=None, transform_refit='always', store_chains=False, metrics=())[source]#

Bases: RedBlueMetropolisHastingsMutation

Rejuvenate particles with red-blue differential-evolution proposals.

Parameters:
  • log_prob_fn (Callable[..., sequince.typing.Array | float] | sequince.target.Target) – Function returning the target log probability for each particle, or a Target instance.

  • n_steps (int) – Number of complete red-blue sweeps to perform.

  • gamma (float | None) – Base differential-evolution scale. If None, use 2.38 / sqrt(2 * n_dimensions).

  • gamma_one_probability (float) – Probability, independently for each proposal, of replacing the ordinary scale with exactly one.

  • gamma_randomization (sequince.steps.mutation.kernels.GammaRandomization) – Scale strategy. "none" uses the fixed base scale; "bilby" multiplies it by an independent Gamma(shape=4, scale=0.25) draw.

  • scale_multipliers (tuple of float) – Positive factors multiplying the ordinary DE scale independently per particle. Explicit unit-scale moves override these factors.

  • scale_weights (tuple of float or None) – Non-negative mixture weights (normalized internally); None is uniform. The kernel is fixed for each call and scale draws are state-independent.

  • noise_scale (float or tuple of float) – Independent Gaussian noise standard deviation in mutation coordinates, either shared or one value per dimension. Must be finite and non-negative. Default is 1e-5; zero disables noise and its RNG draws. With a transform, specify the scale in transformed coordinates.

  • transform (sequince.transforms.ParticleTransform | None) – Optional coordinate transform applied before mutation.

  • transform_refit (sequince.steps.mutation.base.TransformRefit) – Transform refitting policy: "always", "per-context", "once", or a callable receiving the particles and step context.

  • store_chains (bool) – Whether to include the particle state after every complete red-blue sweep in the step output.

  • metrics (sequence of MutationMetric) – Optional diagnostics. For per-scale DE totals, include DEScaleMetrics(scale_multipliers). AdaptDEScaleWeights configures these diagnostics automatically.

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

Validate the effective capacity supplied by an enclosing adapter.

Parameters:
Return type:

None

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]#

Run complete sweeps with fixed-capacity diagnostics under JAX.

Parameters:
  • state (ParticleState) – Initialized particles with shape (n_particles, n_dimensions), floating dtype, and any shape-complete target cache.

  • context (StepContext) – Initialized acceptance and optional functional transform metadata.

  • random_state (object) – Backend-native state returned by orng.RandomGenerator.state(), threaded explicitly through executed sweeps. For JAX this is a PRNG key array. Pass the state rather than the ORNG generator object; ORNG wrappers are reconstructed internally for draws.

  • n_steps (array, shape ()) – Integer budget in [0, max_steps]. Bounds are a caller precondition; compiled runtime values are not checked.

  • max_steps (int) – Static non-negative capacity bounding the executed sweep count.

  • mutation_state (MutationStepState or None) – Continuing block metrics, or None to initialize a new block.

Returns:

  • state (ParticleState) – Updated original-coordinate particles and target cache.

  • context (StepContext) – Updated transform, acceptance metadata and evaluation counters.

  • random_state (object) – Advanced backend-native ORNG state, unchanged when the budget is zero. For JAX this is a PRNG key array.

  • output (dict) – steps is the scalar executed count. Only this many leading rows of acceptance_by_step (max_steps,) and acceptance_by_half (max_steps, 2) are valid. Optional chain has shape (max_steps, n_particles, n_dimensions) in original coordinates. Unused rows are zero. No chain buffer is allocated when storage is disabled.

  • mutation_state (MutationStepState) – Accumulated metrics, independent of padded histories, for the block owner to finalize once. output["metrics"] remains None.

Return type:

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

Notes

Call functional metadata and state/context initialization before JIT. One-time initialization may fit transforms and populate target caches. Block execution with a zero budget performs no transform preparation, target evaluation or RNG draw. Transforms remain fixed per segment.