sequince.steps.mutation.kernels =============================== .. py:module:: sequince.steps.mutation.kernels Attributes ---------- .. autoapisummary:: sequince.steps.mutation.kernels.MutationKernel sequince.steps.mutation.kernels.ProposalFn sequince.steps.mutation.kernels.LogTransitionRatioFn sequince.steps.mutation.kernels.LogDensityFn sequince.steps.mutation.kernels.GammaRandomization sequince.steps.mutation.kernels.MUTATION_KERNELS sequince.steps.mutation.kernels.COMPLEMENTARY_ENSEMBLE_KERNELS Classes ------- .. autoapisummary:: sequince.steps.mutation.kernels.KernelSample sequince.steps.mutation.kernels.TransitionRatioKernel sequince.steps.mutation.kernels.SampleAwareMutationKernel sequince.steps.mutation.kernels.DensityMutationKernel sequince.steps.mutation.kernels.SymmetricMutationKernel sequince.steps.mutation.kernels.ComplementaryEnsembleKernel sequince.steps.mutation.kernels.SymmetricComplementaryEnsembleKernel sequince.steps.mutation.kernels.CallableMutationKernel sequince.steps.mutation.kernels.GaussianRandomWalk sequince.steps.mutation.kernels.DifferentialEvolutionKernel sequince.steps.mutation.kernels.MaskedGaussianRandomWalk sequince.steps.mutation.kernels.AdaptiveMaskedGaussianRandomWalk sequince.steps.mutation.kernels.MixtureMutationKernel Functions --------- .. autoapisummary:: sequince.steps.mutation.kernels.evaluate_log_transition_ratio sequince.steps.mutation.kernels.get_mutation_kernel sequince.steps.mutation.kernels.get_complementary_ensemble_kernel Module Contents --------------- .. py:class:: KernelSample Particles and proposal-local information for one kernel draw. :param particles: Proposed coordinates, with the same shape as the parent particles. :type particles: array :param auxiliary: 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. :type auxiliary: pytree, optional .. rubric:: Notes Acceptance decisions and displacement belong to the mutation layer. Neither kernels nor consumers should mutate this state or its contents. .. py:attribute:: particles :type: sequince.typing.Array .. py:attribute:: auxiliary :type: Any :value: None .. py:class:: TransitionRatioKernel Bases: :py:obj:`_KernelSampler`, :py:obj:`Protocol` Kernel with an array-based transition correction. .. py:method:: log_transition_ratio(from_particles, to_particles) Return ``log q(from | to) - log q(to | from)`` per particle. .. py:class:: SampleAwareMutationKernel Bases: :py:obj:`_KernelSampler`, :py:obj:`Protocol` Kernel whose correction consumes proposal-local state. .. py:method:: log_transition_ratio_from_sample(from_particles, sample) .. py:class:: DensityMutationKernel Bases: :py:obj:`_KernelSampler`, :py:obj:`Protocol` Kernel exposing its transition log density. .. py:method:: log_density(from_particles, to_particles) .. py:data:: MutationKernel .. py:class:: SymmetricMutationKernel Base class for mutation kernels with symmetric transition densities. .. py:method:: log_transition_ratio(from_particles, to_particles) .. py:class:: ComplementaryEnsembleKernel Bases: :py:obj:`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. .. py:method:: sample(particles, complementary_particles, rng) :abstractmethod: Draw particles or proposal state using the frozen complement. .. py:method:: log_transition_ratio(from_particles, to_particles, complementary_particles) :abstractmethod: Return the array correction, or override the sample-aware hook. .. py:class:: SymmetricComplementaryEnsembleKernel Bases: :py:obj:`ComplementaryEnsembleKernel` Base class for symmetric complementary-ensemble kernels. .. py:method:: log_transition_ratio(from_particles, to_particles, complementary_particles) Return the array correction, or override the sample-aware hook. .. py:data:: ProposalFn .. py:data:: LogTransitionRatioFn .. py:data:: LogDensityFn .. py:class:: CallableMutationKernel Adapt callables to the mutation-kernel interface. Exactly one of ``symmetric``, ``log_transition_ratio_fn``, or ``log_density_fn`` must describe the transition correction. .. py:attribute:: proposal_fn :type: ProposalFn .. py:attribute:: symmetric :type: bool :value: False .. py:attribute:: log_transition_ratio_fn :type: LogTransitionRatioFn | None :value: None .. py:attribute:: log_density_fn :type: LogDensityFn | None :value: None .. py:method:: sample(particles, rng) .. py:method:: log_transition_ratio(from_particles, to_particles) .. py:function:: 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 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] 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. .. py:class:: GaussianRandomWalk Bases: :py:obj:`SymmetricMutationKernel` Isotropic Gaussian random-walk mutation kernel. .. py:attribute:: scale :type: float :value: 1.0 .. py:method:: sample(particles, rng) .. py:method:: log_density(from_particles, to_particles) .. py:data:: GammaRandomization .. py:class:: DifferentialEvolutionKernel Bases: :py:obj:`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 :class:`RedBlueMetropolisHastingsMutation` supplies the frozen complementary population for each half-update. Sequince still updates an interacting MCMC population and its complete algorithm is not dynesty. :param gamma: Nominal scale, defaulting to ``2.38 / sqrt(2 * n_dimensions)``. :type gamma: float or None :param gamma_one_probability: Probability of an explicit unit move, overriding all scale factors. :type gamma_one_probability: float :param gamma_randomization: Optional independent Gamma randomization of the nominal scale. :type gamma_randomization: {"none", "bilby"} :param scale_multipliers: Nonempty bank of finite positive factors, sampled per active particle. Factors also multiply Bilby-randomized scales, but never unit moves. :type scale_multipliers: tuple of float :param scale_weights: 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. :type scale_weights: tuple of float or None .. py:attribute:: gamma :type: float | None :value: None .. py:attribute:: gamma_one_probability :type: float :value: 0.1 .. py:attribute:: gamma_randomization :type: GammaRandomization :value: 'none' .. py:attribute:: scale_multipliers :type: tuple[float, ...] :value: (1.0,) .. py:attribute:: scale_weights :type: tuple[float, ...] | None :value: None .. py:method:: sample(particles, complementary_particles, rng) Draw particles or proposal state using the frozen complement. .. py:class:: MaskedGaussianRandomWalk Bases: :py:obj:`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. .. py:attribute:: indices :type: tuple[int, ...] .. py:attribute:: covariance :type: sequince.typing.Array | None :value: None .. py:attribute:: scale :type: float :value: 1.0 .. py:method:: sample(particles, rng) .. py:class:: AdaptiveMaskedGaussianRandomWalk 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. .. py:attribute:: indices :type: tuple[int, ...] .. py:attribute:: scale :type: float | None :value: None .. py:attribute:: regularization :type: float :value: 1e-06 .. py:class:: MixtureMutationKernel Mixture of mutation kernels. Randomly selects one component kernel for each proposal. .. py:attribute:: kernels :type: collections.abc.Sequence[MutationKernel] .. py:attribute:: weights :type: collections.abc.Sequence[float] | None :value: None .. py:method:: sample(particles, rng) .. py:method:: log_transition_ratio_from_sample(from_particles, sample) .. py:data:: MUTATION_KERNELS :type: dict[str, type] .. py:data:: COMPLEMENTARY_ENSEMBLE_KERNELS :type: dict[str, type[ComplementaryEnsembleKernel]] .. py:function:: get_mutation_kernel(name, **kwargs) Construct a named mutation kernel. .. py:function:: get_complementary_ensemble_kernel(name, **kwargs) Construct a named complementary-ensemble mutation kernel.