sequince.steps.mutation.metropolis ================================== .. py:module:: sequince.steps.mutation.metropolis Attributes ---------- .. autoapisummary:: sequince.steps.mutation.metropolis.logger sequince.steps.mutation.metropolis.MutationKernelFactory Classes ------- .. autoapisummary:: sequince.steps.mutation.metropolis.MetropolisHastingsMutation sequince.steps.mutation.metropolis.RedBlueMetropolisHastingsMutation sequince.steps.mutation.metropolis.DifferentialEvolutionMutation Module Contents --------------- .. py:data:: logger .. py:data:: MutationKernelFactory .. py:class:: MetropolisHastingsMutation(log_prob_fn, kernel, *, n_steps = 1, transform = None, transform_refit = 'always', store_chains = False, metrics = ()) Bases: :py:obj:`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. .. py:method:: apply(state, context, rng) .. py:method:: apply_with_mutation_state(state, context, rng, *, n_steps, mutation_state = None) 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. .. py:class:: RedBlueMetropolisHastingsMutation(log_prob_fn, kernel, *, n_steps = 1, transform = None, transform_refit = 'always', store_chains = False, metrics = ()) Bases: :py:obj:`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 :class:`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. .. py:method:: initialize_functional_metadata(state, metadata) Initialize acceptance metadata before tracing red-blue updates. .. py:property:: kernel :type: sequince.steps.mutation.kernels.ComplementaryEnsembleKernel Fixed complementary kernel; replace between mutation calls. .. py:method:: apply(state, context, rng) .. py:method:: apply_with_mutation_state(state, context, rng, *, n_steps, mutation_state = None) 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. .. py:class:: 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 = ()) Bases: :py:obj:`RedBlueMetropolisHastingsMutation` Rejuvenate particles with red-blue differential-evolution proposals. :param log_prob_fn: Function returning the target log probability for each particle, or a :class:`~sequince.target.Target` instance. :param n_steps: Number of complete red-blue sweeps to perform. :param gamma: Base differential-evolution scale. If ``None``, use ``2.38 / sqrt(2 * n_dimensions)``. :param gamma_one_probability: Probability, independently for each proposal, of replacing the ordinary scale with exactly one. :param gamma_randomization: Scale strategy. ``"none"`` uses the fixed base scale; ``"bilby"`` multiplies it by an independent ``Gamma(shape=4, scale=0.25)`` draw. :param scale_multipliers: Positive factors multiplying the ordinary DE scale independently per particle. Explicit unit-scale moves override these factors. :type scale_multipliers: tuple of float :param scale_weights: Non-negative mixture weights (normalized internally); None is uniform. The kernel is fixed for each call and scale draws are state-independent. :type scale_weights: tuple of float or None :param transform: Optional coordinate transform applied before mutation. :param transform_refit: Transform refitting policy: ``"always"``, ``"per-context"``, ``"once"``, or a callable receiving the particles and step context. :param store_chains: Whether to include the particle state after every complete red-blue sweep in the step output. :param metrics: Optional diagnostics. For per-scale DE totals, include DEScaleMetrics(scale_multipliers). AdaptDEScaleWeights configures these diagnostics automatically. :type metrics: sequence of MutationMetric