Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
107 changes: 92 additions & 15 deletions docs/user_guide/sampling_options/mutation_configuration.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand All @@ -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
-----------------
Expand Down Expand Up @@ -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
Expand All @@ -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.
65 changes: 57 additions & 8 deletions src/sequince/steps/mutation/factory.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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]",
Expand All @@ -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
Expand Down Expand Up @@ -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:
Expand All @@ -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,
Expand Down
Loading
Loading