From 14bfa83bf47ed133555352d2440e2920316f81d2 Mon Sep 17 00:00:00 2001 From: "Michael J. Williams" Date: Fri, 13 Nov 2026 09:40:16 +0100 Subject: [PATCH 1/4] ENH(mutation): expose adaptive DE scale weights in the factory --- src/sequince/steps/mutation/factory.py | 65 ++++++++++++++++++++++---- 1 file changed, 57 insertions(+), 8 deletions(-) diff --git a/src/sequince/steps/mutation/factory.py b/src/sequince/steps/mutation/factory.py index 065286f..8ca1155 100644 --- a/src/sequince/steps/mutation/factory.py +++ b/src/sequince/steps/mutation/factory.py @@ -3,12 +3,14 @@ import math from collections.abc import Callable, Mapping from numbers import Integral, Real -from typing import Any +from typing import Any, cast from ...target import Target from ...transforms import ParticleTransform -from ..base import SMCStep +from ..base import FixedLengthMutation, SMCStep +from .adaptive.de import AdaptDEScaleWeights from .adaptive.policies.acceptance import AcceptanceRatePolicy +from .adaptive.policies.de import DEScaleWeightPolicy, ESJDScaleWeightPolicy from .adaptive.steps import AdaptMutationSteps from .blackjax import BlackJAXMutation from .emcee import EmceeMutation @@ -72,6 +74,32 @@ def _acceptance_policy( ) +def _scale_weight_policy( + policy: str | DEScaleWeightPolicy | None, + policy_kwargs: Mapping[str, Any], +) -> DEScaleWeightPolicy | None: + """Resolve a named scale-weight policy or preserve a supplied instance.""" + if isinstance(policy, str): + policies: dict[str, Callable[..., DEScaleWeightPolicy]] = { + "esjd": ESJDScaleWeightPolicy, + } + try: + constructor = policies[policy] + except KeyError as exc: + valid = ", ".join(sorted(policies)) + raise ValueError( + f"Unknown scale-weight policy '{policy}'. " + f"Valid options are: {valid}." + ) from exc + return constructor(**policy_kwargs) + if policy_kwargs: + raise ValueError( + "scale_weight_policy_kwargs can only be used with a named " + "scale_weight_policy." + ) + return policy + + def get_mutation_step( mutation: str | SMCStep | None, target: "Target | Callable[..., Any]", @@ -93,7 +121,8 @@ def get_mutation_step( mutation_n_steps : int, optional Fixed total budget, or initial budget when adaptation is enabled. mutation_kwargs : dict or None, optional - Additional mutation constructor options. + Additional mutation constructor options. Includes configuration of + adaptive parameter policies for mutation kernels that support them. adaptive_mutation : Mapping[str, object] or None, optional Named miniPCN and differential-evolution mutations support ``enabled`` (default True), ``min_steps`` (0), ``max_steps`` (1000), and @@ -193,11 +222,33 @@ def get_mutation_step( **kwargs, ) elif mutation == "differential-evolution": - mutation_step = DifferentialEvolutionMutation( + adapt_scale_weights = kwargs.pop("adapt_scale_weights", False) + if not isinstance(adapt_scale_weights, bool): + raise TypeError("adapt_scale_weights must be a boolean.") + scale_weight_policy = kwargs.pop("scale_weight_policy", None) + policy_kwargs = dict( + kwargs.pop("scale_weight_policy_kwargs", {}) or {} + ) + if ( + scale_weight_policy is not None or policy_kwargs + ) and not adapt_scale_weights: + raise ValueError( + "scale_weight_policy configuration requires " + "adapt_scale_weights=True." + ) + scale_weight_policy = _scale_weight_policy( + scale_weight_policy, policy_kwargs + ) + de = DifferentialEvolutionMutation( target, n_steps=mutation_n_steps, **kwargs, ) + mutation_step = ( + AdaptDEScaleWeights(de, policy=scale_weight_policy) + if adapt_scale_weights + else de + ) elif mutation == "none" or mutation is None: mutation_step = None else: @@ -208,11 +259,9 @@ def get_mutation_step( "'none', or an SMCStep instance." ) if policy is not None: - assert isinstance( - mutation_step, (MiniPCNMutation, DifferentialEvolutionMutation) - ) return AdaptMutationSteps( - mutation_step, + # AdaptMutationSteps validates the fixed-length interface. + cast(FixedLengthMutation, mutation_step), policy, initial_steps=mutation_n_steps, min_steps=policy.min_steps, From 01fbae8ca192b0753dd2952d6dfe9827cd818877 Mon Sep 17 00:00:00 2001 From: "Michael J. Williams" Date: Fri, 13 Nov 2026 09:40:23 +0100 Subject: [PATCH 2/4] DOC(mutation): document adaptive mutation configuration --- .../mutation_configuration.rst | 107 +++++++++++++++--- 1 file changed, 92 insertions(+), 15 deletions(-) diff --git a/docs/user_guide/sampling_options/mutation_configuration.rst b/docs/user_guide/sampling_options/mutation_configuration.rst index 1c35ba6..15fc4f4 100644 --- a/docs/user_guide/sampling_options/mutation_configuration.rst +++ b/docs/user_guide/sampling_options/mutation_configuration.rst @@ -117,8 +117,8 @@ are also selected. Particle-aligned auxiliary data works with batch-preserving mutation and BlackJAX; emcee and Eryn reject it because their callbacks do not expose the original walker indices. -Blocked updates, repetition, and adaptation -------------------------------------------- +Blocked updates and repetition +------------------------------ Use these steps to compose mutation updates: @@ -127,18 +127,6 @@ Use these steps to compose mutation updates: Block indices refer to transformed coordinates. * :class:`~sequince.steps.mutation.repeated.RepeatedMutationStep`: split a total transition count across fixed rounds, with an optional step after each round. -* :class:`~sequince.steps.mutation.adaptive.steps.AdaptMutationSteps`: choose - the next iteration's transition count from completed diagnostics. -* :class:`~sequince.steps.mutation.adaptive.minipcn.AdaptiveMiniPCNMutation`: - tune MiniPCN rho between iterations. Requires equal, finite weights and a - child with ``adaptive=False``. -* :class:`~sequince.steps.mutation.adaptive.de.AdaptDEScaleWeights`: tune DE - mixture weights between iterations. -* :class:`~sequince.steps.mutation.adaptive.proposal.AdaptiveGaussianProposal`: - update a scale in context metadata for a kernel factory to read. - -The adaptation wrappers support eager execution only. Place conditional steps -outside them, for example ``MutateIfResampled(mutation_step)``. Prebuilt samplers ----------------- @@ -168,8 +156,16 @@ and options directly: the helper does not apply ``mutation_n_steps`` or and the API links above for method-specific options and outputs. +Adaptive mutation kernels +------------------------- + +Adaptation can adjust the mutation budget or proposal parameters between +iterations using completed diagnostics. The adaptation wrappers support eager +execution only. Place conditional steps outside them, for example +``MutateIfResampled(mutation_step)``. + Acceptance-based mutation budgets ---------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ For standard and persistent SMC, set ``adaptive_mutation`` to adjust the number of transitions from the previous iteration's acceptance rate. Named @@ -196,3 +192,84 @@ and bounds. See :func:`~sequince.steps.mutation.factory.get_mutation_step` for option details, or use :class:`~sequince.steps.mutation.adaptive.steps.AdaptMutationSteps` in a custom pipeline. + +Differential-evolution scale weights +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +For the named ``"differential-evolution"`` mutation, set +``mutation_kwargs={"adapt_scale_weights": True}`` to adapt mixture weights +with :class:`~sequince.steps.mutation.adaptive.de.AdaptDEScaleWeights` and its +default :class:`~sequince.steps.mutation.adaptive.policies.de.ESJDScaleWeightPolicy`. +The factory consumes this flag; ``scale_multipliers`` and initial +``scale_weights`` remain constructor options. Existing defaults are unchanged, +and scale-weight adaptation defaults to ``False``. + +Pass a policy instance as ``scale_weight_policy`` in ``mutation_kwargs`` to +customize adaptation, for example: + +.. code-block:: python + + from sequince.steps.mutation import ESJDScaleWeightPolicy + + mutation_kwargs = { + "adapt_scale_weights": True, + "scale_weight_policy": ESJDScaleWeightPolicy( + learning_rate=0.2, + exploration_probability=0.05, + min_attempts=10, + ), + } + +Alternatively, specify the policy by name and pass its constructor options +separately: + +.. code-block:: python + + mutation_kwargs = { + "adapt_scale_weights": True, + "scale_weight_policy": "esjd", + "scale_weight_policy_kwargs": {"learning_rate": 0.2, "min_attempts": 10}, + } + +``"esjd"`` is currently the supported policy name. +``scale_weight_policy_kwargs`` requires a named policy; configure policy +instances directly. Custom policies implement the +:class:`~sequince.steps.mutation.adaptive.policies.de.DEScaleWeightPolicy` +interface. Omit ``scale_weight_policy`` or set it to ``None`` to use the default +ESJD policy. Supplying a policy requires ``adapt_scale_weights=True``. + +Scale-weight adaptation requires eager execution. Enable it independently or +combine it with adaptive mutation, for example through +:func:`~sequince.prebuilt_samplers.make_persistent_bayesian_smc`: + +.. code-block:: python + + smc, posterior, metadata = make_persistent_bayesian_smc( + log_prior=log_prior, + log_likelihood=log_likelihood, + mutation="differential-evolution", + mutation_kwargs={ + "scale_multipliers": (0.25, 1.0, 4.0), + "adapt_scale_weights": True, + }, + adaptive_mutation={"target_accepted_moves": 5.0}, + ) + +These multipliers are illustrative. When both options are enabled, the factory +constructs ``AdaptMutationSteps(AdaptDEScaleWeights(de), ...)``: the outer +wrapper sets the sweep count and the inner wrapper adapts mixture weights. +Both decisions use completed blocks and remain fixed within each block. + +MiniPCN proposal adaptation +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In a custom pipeline, use +:class:`~sequince.steps.mutation.adaptive.minipcn.AdaptiveMiniPCNMutation` +to tune MiniPCN rho between iterations. It requires equal, finite weights and +a child mutation with ``adaptive=False``. + +Gaussian proposal scale adaptation +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use :class:`~sequince.steps.mutation.adaptive.proposal.AdaptiveGaussianProposal` +to update a scale in context metadata for a kernel factory to read. From 61f170310cdd9891853c0456a8f308bf101d568b Mon Sep 17 00:00:00 2001 From: "Michael J. Williams" Date: Fri, 13 Nov 2026 09:40:29 +0100 Subject: [PATCH 3/4] TST(mutation): cover factory scale-weight adaptation and policies --- tests/test_mutation/test_factory.py | 199 ++++++++++++++++++++++++++++ tests/test_prebuilt_samplers.py | 30 +++++ 2 files changed, 229 insertions(+) diff --git a/tests/test_mutation/test_factory.py b/tests/test_mutation/test_factory.py index 57782a2..95190ff 100644 --- a/tests/test_mutation/test_factory.py +++ b/tests/test_mutation/test_factory.py @@ -7,6 +7,8 @@ from sequince.steps import DifferentialEvolutionMutation as PublicDEMutation from sequince.steps.base import SMCStep, StepContext from sequince.steps.mutation import ( + AdaptDEScaleWeights, + AdaptMutationSteps, BlackJAXMutation, DifferentialEvolutionKernel, DifferentialEvolutionMutation, @@ -17,6 +19,7 @@ RedBlueMetropolisHastingsMutation, get_mutation_step, ) +from sequince.steps.mutation.adaptive.policies.de import ESJDScaleWeightPolicy from sequince.steps.mutation.metropolis import ( DifferentialEvolutionMutation as DirectDEMutation, ) @@ -154,6 +157,202 @@ def test_get_mutation_step_constructs_differential_evolution( assert output["steps"] == 2 +@pytest.mark.parametrize("adaptive_steps", [False, True]) +def test_factory_adapts_de_scale_weights( + adaptive_steps: bool, + standard_normal_posterior, + particle_state, + context_factory, + rng, +) -> None: + kwargs = { + "scale_multipliers": (0.25, 1.0, 4.0), + "scale_weights": (0.2, 0.5, 0.3), + "adapt_scale_weights": True, + } + step = get_mutation_step( + "differential-evolution", + standard_normal_posterior, + mutation_n_steps=2, + mutation_kwargs=kwargs, + adaptive_mutation=( + {"target_accepted_moves": 100.0, "max_steps": 4} + if adaptive_steps + else None + ), + ) + if adaptive_steps: + assert isinstance(step, AdaptMutationSteps) + adapter = step.mutation + else: + adapter = step + assert isinstance(adapter, AdaptDEScaleWeights) + assert adapter.policy == ESJDScaleWeightPolicy() + de = adapter.mutation + assert isinstance(de, DifferentialEvolutionMutation) + assert de.kernel.scale_multipliers == kwargs["scale_multipliers"] + assert de.kernel.scale_weights == pytest.approx(kwargs["scale_weights"]) + assert kwargs["adapt_scale_weights"] is True + + state, _, output = step(particle_state, context_factory(t=0), rng) + assert output["metrics"].n_steps == 2 + assert adapter.current_weights == pytest.approx( + tuple(0.9 * weight + 0.1 / 3 for weight in (0.2, 0.5, 0.3)) + ) + assert adapter.next_weights is not None + pending_weights = adapter.next_weights + if adaptive_steps: + assert step.next_n_steps == 4 + _, _, output = step(state, context_factory(t=1), rng) + assert output["metrics"].n_steps == (4 if adaptive_steps else 2) + assert adapter.current_weights == pytest.approx(pending_weights) + assert "de_scales" in output["metrics"].values + + +@pytest.mark.parametrize("adaptive_steps", [False, True]) +@pytest.mark.parametrize("named", [False, True]) +def test_factory_de_scale_weight_policy( + adaptive_steps: bool, named: bool, standard_normal_posterior +) -> None: + policy = ESJDScaleWeightPolicy( + learning_rate=0.2, exploration_probability=0.05, min_attempts=10 + ) + kwargs = {"adapt_scale_weights": True, "scale_weight_policy": policy} + if named: + kwargs = { + "adapt_scale_weights": True, + "scale_weight_policy": "esjd", + "scale_weight_policy_kwargs": { + "learning_rate": 0.2, + "exploration_probability": 0.05, + "min_attempts": 10, + }, + } + step = get_mutation_step( + "differential-evolution", + standard_normal_posterior, + mutation_kwargs=kwargs, + adaptive_mutation={} if adaptive_steps else None, + ) + if adaptive_steps: + assert isinstance(step, AdaptMutationSteps) + step = step.mutation + assert isinstance(step, AdaptDEScaleWeights) + assert step.policy == policy + if not named: + assert step.policy is policy + assert kwargs["scale_weight_policy"] is policy + else: + assert kwargs["scale_weight_policy"] == "esjd" + + +@pytest.mark.parametrize( + ("config", "error", "message"), + [ + ( + {"scale_weight_policy": "unknown"}, + ValueError, + "Valid options.*esjd", + ), + ( + {"scale_weight_policy_kwargs": {"min_attempts": 10}}, + ValueError, + "only be used with a named", + ), + ( + { + "scale_weight_policy": ESJDScaleWeightPolicy(), + "scale_weight_policy_kwargs": {"min_attempts": 10}, + }, + ValueError, + "only be used with a named", + ), + ( + { + "scale_weight_policy": "esjd", + "scale_weight_policy_kwargs": {"unknown": 1}, + }, + TypeError, + "unexpected keyword", + ), + ( + { + "scale_weight_policy": "esjd", + "scale_weight_policy_kwargs": {"learning_rate": 0}, + }, + ValueError, + "learning_rate", + ), + ], +) +def test_factory_invalid_named_scale_weight_policy( + config, error, message, standard_normal_posterior +) -> None: + with pytest.raises(error, match=message): + get_mutation_step( + "differential-evolution", + standard_normal_posterior, + mutation_kwargs={"adapt_scale_weights": True, **config}, + ) + + +@pytest.mark.parametrize("enabled", [None, False]) +def test_factory_de_scale_weight_policy_requires_adaptation( + enabled: bool | None, standard_normal_posterior +) -> None: + kwargs = {"scale_weight_policy": ESJDScaleWeightPolicy()} + if enabled is not None: + kwargs["adapt_scale_weights"] = enabled + with pytest.raises(ValueError, match="requires adapt_scale_weights=True"): + get_mutation_step( + "differential-evolution", + standard_normal_posterior, + mutation_kwargs=kwargs, + ) + + +def test_factory_de_rejects_invalid_scale_weight_policy( + standard_normal_posterior, +) -> None: + with pytest.raises(TypeError, match="implement initialise.*update"): + get_mutation_step( + "differential-evolution", + standard_normal_posterior, + mutation_kwargs={ + "adapt_scale_weights": True, + "scale_weight_policy": object(), + }, + ) + + +@pytest.mark.parametrize("kwargs", [{}, {"adapt_scale_weights": False}]) +def test_factory_de_scale_weights_default( + kwargs, standard_normal_posterior +) -> None: + step = get_mutation_step( + "differential-evolution", + standard_normal_posterior, + mutation_kwargs=kwargs, + ) + assert isinstance(step, DifferentialEvolutionMutation) + assert step.kernel.scale_multipliers == (1.0,) + assert step.kernel.scale_weights == (1.0,) + + +@pytest.mark.parametrize("flag", [None, 0, 1, "true", {}]) +def test_factory_de_scale_weights_requires_boolean( + flag, standard_normal_posterior +) -> None: + with pytest.raises( + TypeError, match="adapt_scale_weights must be a boolean" + ): + get_mutation_step( + "differential-evolution", + standard_normal_posterior, + mutation_kwargs={"adapt_scale_weights": flag}, + ) + + def test_get_mutation_step_constructs_named_red_blue_kernel( standard_normal_posterior, ) -> None: diff --git a/tests/test_prebuilt_samplers.py b/tests/test_prebuilt_samplers.py index 44d8352..c4e5365 100644 --- a/tests/test_prebuilt_samplers.py +++ b/tests/test_prebuilt_samplers.py @@ -695,6 +695,36 @@ def test_prebuilt_acceptance_adaptation(factory, name, enabled) -> None: assert isinstance(mutation, AdaptMutationSteps) == enabled +@pytest.mark.parametrize( + "factory", [make_standard_bayesian_smc, make_persistent_bayesian_smc] +) +def test_prebuilt_combines_de_adaptations(factory) -> None: + from sequince.steps.mutation import ( + AdaptDEScaleWeights, + AdaptMutationSteps, + DifferentialEvolutionMutation, + ) + + smc, _, _ = factory( + _quadratic_log_prior, + _zero_log_likelihood, + mutation="differential-evolution", + mutation_kwargs={ + "scale_multipliers": (0.25, 1.0, 4.0), + "adapt_scale_weights": True, + "scale_weight_policy": "esjd", + "scale_weight_policy_kwargs": {"learning_rate": 0.2}, + }, + adaptive_mutation={"target_accepted_moves": 5.0}, + logging_frequency=0, + ) + outer = smc.config.steps[-1] + assert isinstance(outer, AdaptMutationSteps) + assert isinstance(outer.mutation, AdaptDEScaleWeights) + assert isinstance(outer.mutation.mutation, DifferentialEvolutionMutation) + assert outer.mutation.policy.learning_rate == 0.2 + + @pytest.mark.parametrize("mutation", ["minipcn", "differential-evolution"]) def test_standard_adaptive_checkpoint_resume(tmp_path, mutation) -> None: from sequince.checkpoint import PickleCheckpointWriter, SMCCheckpoint From 6b7f0625436280dcd34301b39447c96ca3851ea4 Mon Sep 17 00:00:00 2001 From: "Michael J. Williams" Date: Fri, 13 Nov 2026 09:42:00 +0100 Subject: [PATCH 4/4] DOC: add changelog entry for #147 --- CHANGELOG.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d45807f..626b085 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,8 +8,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Added -- Optional acceptance-based mutation budgets via `adaptive_mutation` for - MiniPCN and differential evolution mutations in standard and persistent SMC. +- Support differential-evolution scale-weight adaptation through the mutation + step factory. ([#147](https://github.com/sequince-dev/sequince/pull/147)) +- Support acceptance-based mutation budgets through the mutation step factory. ([#144](https://github.com/sequince-dev/sequince/pull/144)) - Allow adaptive SMC to set `beta_tolerance` independently of the minimum beta increment, including through `make_standard_bayesian_smc`'s