sequince.steps.mutation.metropolis

sequince.steps.mutation.metropolis#

Attributes#

logger

MutationKernelFactory

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, 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.

  • 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.