sequince.steps.mutation.kernels

sequince.steps.mutation.kernels#

Attributes#

`MutationKernel`
`ProposalFn`
`LogTransitionRatioFn`
`LogDensityFn`
`GammaRandomization`
`MUTATION_KERNELS`
`COMPLEMENTARY_ENSEMBLE_KERNELS`

Classes#

`KernelSample`	Particles and proposal-local information for one kernel draw.
`TransitionRatioKernel`	Kernel with an array-based transition correction.
`SampleAwareMutationKernel`	Kernel whose correction consumes proposal-local state.
`DensityMutationKernel`	Kernel exposing its transition log density.
`SymmetricMutationKernel`	Base class for mutation kernels with symmetric transition densities.
`ComplementaryEnsembleKernel`	Kernel using a frozen complement and either correction hook.
`SymmetricComplementaryEnsembleKernel`	Base class for symmetric complementary-ensemble kernels.
`CallableMutationKernel`	Adapt callables to the mutation-kernel interface.
`GaussianRandomWalk`	Isotropic Gaussian random-walk mutation kernel.
`DifferentialEvolutionKernel`	Differential-evolution proposals from a frozen complementary ensemble.
`MaskedGaussianRandomWalk`	Multivariate Gaussian random walk on selected particle coordinates.
`AdaptiveMaskedGaussianRandomWalk`	Build a masked Gaussian kernel from the current particle covariance.
`MixtureMutationKernel`	Mixture of mutation kernels.

Functions#

`evaluate_log_transition_ratio`(…)	Evaluate a transition ratio.
`get_mutation_kernel`(name, **kwargs)	Construct a named mutation kernel.
`get_complementary_ensemble_kernel`(name, **kwargs)	Construct a named complementary-ensemble mutation kernel.

Module Contents#

class sequince.steps.mutation.kernels.KernelSample[source]#

Particles and proposal-local information for one kernel draw.

Parameters:

particles (array) – Proposed coordinates, with the same shape as the parent particles.
auxiliary (pytree, optional) – Kernel-specific pytree data needed for transition corrections or diagnostics. DE stores arrays aligned with the active particles; mixtures store their selected component and its proposal state. Complementary kernels must use arrays with an active-particle leading dimension so the mutation can combine both half-updates.

Notes

Acceptance decisions and displacement belong to the mutation layer. Neither kernels nor consumers should mutate this state or its contents.

particles: sequince.typing.Array#

auxiliary: Any = None#

class sequince.steps.mutation.kernels.TransitionRatioKernel[source]#

Bases: _KernelSampler, Protocol

Kernel with an array-based transition correction.

log_transition_ratio(from_particles, to_particles)[source]#

Return log q(from | to) - log q(to | from) per particle.

Parameters:

from_particles (sequince.typing.Array)
to_particles (sequince.typing.Array)

Return type:

sequince.typing.Array

class sequince.steps.mutation.kernels.SampleAwareMutationKernel[source]#

Bases: _KernelSampler, Protocol

Kernel whose correction consumes proposal-local state.

log_transition_ratio_from_sample(from_particles, sample)[source]#

Parameters:

from_particles (sequince.typing.Array)
sample (KernelSample)

Return type:

sequince.typing.Array

class sequince.steps.mutation.kernels.DensityMutationKernel[source]#

Bases: _KernelSampler, Protocol

Kernel exposing its transition log density.

log_density(from_particles, to_particles)[source]#

Parameters:

from_particles (sequince.typing.Array)
to_particles (sequince.typing.Array)

Return type:

sequince.typing.Array

sequince.steps.mutation.kernels.MutationKernel#

class sequince.steps.mutation.kernels.SymmetricMutationKernel[source]#

Base class for mutation kernels with symmetric transition densities.

log_transition_ratio(from_particles, to_particles)[source]#

Parameters:

from_particles (sequince.typing.Array)
to_particles (sequince.typing.Array)

Return type:

sequince.typing.Array

class sequince.steps.mutation.kernels.ComplementaryEnsembleKernel[source]#

Bases: abc.ABC

Kernel using a frozen complement and either correction hook.

Auxiliary pytrees must match between half-updates. Every leaf must be an array with an active-particle leading dimension; None nodes are permitted. Treat auxiliary data as read-only.

abstractmethod sample(particles, complementary_particles, rng)[source]#

Draw particles or proposal state using the frozen complement.

Parameters:

particles (sequince.typing.Array)
complementary_particles (sequince.typing.Array)
rng (orng.RandomGenerator)

Return type:

sequince.typing.Array | KernelSample

abstractmethod log_transition_ratio(from_particles, to_particles, complementary_particles)[source]#

Return the array correction, or override the sample-aware hook.

Parameters:

from_particles (sequince.typing.Array)
to_particles (sequince.typing.Array)
complementary_particles (sequince.typing.Array)

Return type:

sequince.typing.Array

class sequince.steps.mutation.kernels.SymmetricComplementaryEnsembleKernel[source]#

Bases: ComplementaryEnsembleKernel

Base class for symmetric complementary-ensemble kernels.

log_transition_ratio(from_particles, to_particles, complementary_particles)[source]#

Return the array correction, or override the sample-aware hook.

Parameters:

from_particles (sequince.typing.Array)
to_particles (sequince.typing.Array)
complementary_particles (sequince.typing.Array)

Return type:

sequince.typing.Array

sequince.steps.mutation.kernels.ProposalFn#

sequince.steps.mutation.kernels.LogTransitionRatioFn#

sequince.steps.mutation.kernels.LogDensityFn#

class sequince.steps.mutation.kernels.CallableMutationKernel[source]#

Adapt callables to the mutation-kernel interface.

Exactly one of symmetric, log_transition_ratio_fn, or log_density_fn must describe the transition correction.

proposal_fn: ProposalFn#

symmetric: bool = False#

log_transition_ratio_fn: LogTransitionRatioFn | None = None#

log_density_fn: LogDensityFn | None = None#

sample(particles, rng)[source]#

Parameters:

particles (sequince.typing.Array)
rng (orng.RandomGenerator)

Return type:

sequince.typing.Array

log_transition_ratio(from_particles, to_particles)[source]#

Parameters:

from_particles (sequince.typing.Array)
to_particles (sequince.typing.Array)

Return type:

sequince.typing.Array

sequince.steps.mutation.kernels.evaluate_log_transition_ratio(kernel: object, from_particles: sequince.typing.Array, proposal: sequince.typing.Array | KernelSample, complementary_particles: sequince.typing.Array | None = None, *, return_counts: Literal[False] = False) → sequince.typing.Array[source]#
sequince.steps.mutation.kernels.evaluate_log_transition_ratio(kernel: object, from_particles: sequince.typing.Array, proposal: sequince.typing.Array | KernelSample, complementary_particles: sequince.typing.Array | None = None, *, return_counts: Literal[True]) → tuple[sequince.typing.Array, sequince.target.EvaluationCounts]
sequince.steps.mutation.kernels.evaluate_log_transition_ratio(kernel: object, from_particles: sequince.typing.Array, proposal: sequince.typing.Array | KernelSample, complementary_particles: sequince.typing.Array | None = None, *, return_counts: bool) → sequince.typing.Array | tuple[sequince.typing.Array, sequince.target.EvaluationCounts]: Evaluate a transition ratio.

class sequince.steps.mutation.kernels.GaussianRandomWalk[source]#

Bases: SymmetricMutationKernel

Isotropic Gaussian random-walk mutation kernel.

scale: float = 1.0#

sample(particles, rng)[source]#

Parameters:

particles (sequince.typing.Array)
rng (orng.RandomGenerator)

Return type:

sequince.typing.Array

log_density(from_particles, to_particles)[source]#

Parameters:

from_particles (sequince.typing.Array)
to_particles (sequince.typing.Array)

Return type:

sequince.typing.Array

sequince.steps.mutation.kernels.GammaRandomization#

class sequince.steps.mutation.kernels.DifferentialEvolutionKernel[source]#

Bases: SymmetricComplementaryEnsembleKernel

Differential-evolution proposals from a frozen complementary ensemble.

"none" uses standard fixed-scale DE-MCMC. "bilby" multiplies the base scale by an independent Gamma(shape=4, scale=0.25) draw for each proposal, matching Bilby-style dynesty scaling. When gamma is omitted, the base scale is 2.38 / sqrt(2 * n_dimensions).

gamma_one_probability controls occasional unit-scale moves. A RedBlueMetropolisHastingsMutation supplies the frozen complementary population for each half-update. Sequince still updates an interacting MCMC population and its complete algorithm is not dynesty.

Parameters:

gamma (float or None) – Nominal scale, defaulting to 2.38 / sqrt(2 * n_dimensions).
gamma_one_probability (float) – Probability of an explicit unit move, overriding all scale factors.
gamma_randomization ({"none", "bilby"}) – Optional independent Gamma randomization of the nominal scale.
scale_multipliers (tuple of float) – Nonempty bank of finite positive factors, sampled per active particle. Factors also multiply Bilby-randomized scales, but never unit moves.
scale_weights (tuple of float or None) – Finite non-negative categorical weights, normalized on construction. None assigns equal weights. Configuration is immutable and selection is state-independent, so the global proposal remains symmetric. Use dataclasses.replace to construct weights for a later stage.

gamma: float | None = None#

gamma_one_probability: float = 0.1#

gamma_randomization: GammaRandomization = 'none'#

scale_multipliers: tuple[float, ...] = (1.0,)#

scale_weights: tuple[float, ...] | None = None#

sample(particles, complementary_particles, rng)[source]#

Draw particles or proposal state using the frozen complement.

Parameters:

particles (sequince.typing.Array)
complementary_particles (sequince.typing.Array)
rng (orng.RandomGenerator)

Return type:

KernelSample

class sequince.steps.mutation.kernels.MaskedGaussianRandomWalk[source]#

Bases: SymmetricMutationKernel

Multivariate Gaussian random walk on selected particle coordinates.

Inactive coordinates are copied without modification. covariance is the covariance within the active subspace; scale multiplies its Cholesky factor and therefore acts as a standard-deviation multiplier.

indices: tuple[int, ...]#

covariance: sequince.typing.Array | None = None#

scale: float = 1.0#

sample(particles, rng)[source]#

Parameters:

particles (sequince.typing.Array)
rng (orng.RandomGenerator)

Return type:

sequince.typing.Array

class sequince.steps.mutation.kernels.AdaptiveMaskedGaussianRandomWalk[source]#

Build a masked Gaussian kernel from the current particle covariance.

The covariance is estimated once at the beginning of each mutation block, keeping the resulting proposal symmetric throughout that block.

indices: tuple[int, ...]#

scale: float | None = None#

regularization: float = 1e-06#

class sequince.steps.mutation.kernels.MixtureMutationKernel[source]#

Mixture of mutation kernels.

Randomly selects one component kernel for each proposal.

kernels: collections.abc.Sequence[MutationKernel]#

weights: collections.abc.Sequence[float] | None = None#

sample(particles, rng)[source]#

Parameters:

particles (sequince.typing.Array)
rng (orng.RandomGenerator)

Return type:

KernelSample

log_transition_ratio_from_sample(from_particles, sample)[source]#

Parameters:

from_particles (sequince.typing.Array)
sample (KernelSample)

Return type:

sequince.typing.Array

sequince.steps.mutation.kernels.MUTATION_KERNELS: dict[str, type]#

sequince.steps.mutation.kernels.COMPLEMENTARY_ENSEMBLE_KERNELS: dict[str, type[ComplementaryEnsembleKernel]]#

sequince.steps.mutation.kernels.get_mutation_kernel(name, **kwargs)[source]#

Construct a named mutation kernel.

Parameters:

name (str)
kwargs (Any)

Return type:

MutationKernel

sequince.steps.mutation.kernels.get_complementary_ensemble_kernel(name, **kwargs)[source]#

Construct a named complementary-ensemble mutation kernel.

Parameters:

name (str)
kwargs (Any)

Return type:

ComplementaryEnsembleKernel