sequince.steps.mutation.metropolis#
Attributes#
Classes#
Rejuvenate particles with a custom Metropolis-Hastings kernel. |
|
Metropolis-Hastings updates using complementary particle ensembles. |
|
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.MutationStepRejuvenate 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:
state (sequince.state.ParticleState)
context (sequince.steps.context.StepContext)
rng (orng.RandomGenerator)
- 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=Noneto 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
applyorapply_with_n_stepsfor a complete standalone block. RepeatedMutationStep uses this method to continue across rounds and finalizes metrics once after the complete block.- Parameters:
state (sequince.state.ParticleState)
context (sequince.steps.context.StepContext)
rng (orng.RandomGenerator)
n_steps (int)
mutation_state (sequince.steps.mutation.metrics.MutationStepState | None)
- 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:
MetropolisHastingsMutationMetropolis-Hastings updates using complementary particle ensembles.
Each of
n_stepsis 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 persistentComplementaryEnsembleKernelreceives 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:
log_prob_fn (Callable[..., sequince.typing.Array | float] | sequince.target.Target)
kernel (sequince.steps.mutation.kernels.ComplementaryEnsembleKernel)
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])
- initialize_functional_metadata(state, metadata)[source]#
Initialize acceptance metadata before tracing red-blue updates.
- Parameters:
state (sequince.state.ParticleState)
metadata (collections.abc.Mapping[str, Any])
- Return type:
collections.abc.Mapping[str, Any]
- property kernel: sequince.steps.mutation.kernels.ComplementaryEnsembleKernel#
Fixed complementary kernel; replace between mutation calls.
- 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, 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=Noneto 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
applyorapply_with_n_stepsfor a complete standalone block. RepeatedMutationStep uses this method to continue across rounds and finalizes metrics once after the complete block.- Parameters:
state (sequince.state.ParticleState)
context (sequince.steps.context.StepContext)
rng (orng.RandomGenerator)
n_steps (int)
mutation_state (sequince.steps.mutation.metrics.MutationStepState | None)
- 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:
RedBlueMetropolisHastingsMutationRejuvenate 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
Targetinstance.n_steps (int) – Number of complete red-blue sweeps to perform.
gamma (float | None) – Base differential-evolution scale. If
None, use2.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 independentGamma(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:
config (sequince.smc.SMCConfig)
state (sequince.state.ParticleState)
max_steps (int | None)
- 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:
state (sequince.state.ParticleState)
context (sequince.steps.context.StepContext)
random_state (Any)
- 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) –
stepsis the scalar executed count. Only this many leading rows ofacceptance_by_step(max_steps,) andacceptance_by_half(max_steps, 2) are valid. Optionalchainhas 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.