diff --git a/CHANGELOG.md b/CHANGELOG.md index 626b085d..cb4d2859 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,9 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ### Added +- Support JAX JIT execution of differential-evolution mutation with adaptive + step budgets, including repeated mutation blocks. + - 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. @@ -17,6 +20,20 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `weighting_kwargs`. The default continues to use `min_delta` as the tolerance. ([#146](https://github.com/sequince-dev/sequince/pull/146)) +### Changed + +- Store eager mutation budgets in a complete `MutationBudgetState`, with both + budgets initially equal to `initial_steps` and unset iterations marked -1. + The adapter checkpoint now contains a `budget` mapping; old optional-field + adapter checkpoints are not supported. Eager and functional execution share + initialization and transition rules, including advancement without an update. + +- Use the same floating-point calculation for eager and functional acceptance + budgets. Near integer thresholds, eager decisions may differ from the previous + exact-ratio ceiling (for example, 11 rather than 12), changing subsequent RNG + consumption and sample paths. Acceptance policies now require `max_steps <= + 2**24` in both modes; saved pending checkpoint decisions are preserved. + ## [0.1.0] - 2026-10-29 First stable release. Changes below are relative to 0.1.0b1. diff --git a/docs/user_guide/sampling_options/mutation_configuration.rst b/docs/user_guide/sampling_options/mutation_configuration.rst index 15fc4f40..0e5c6c40 100644 --- a/docs/user_guide/sampling_options/mutation_configuration.rst +++ b/docs/user_guide/sampling_options/mutation_configuration.rst @@ -142,7 +142,7 @@ Install ``sequince[minipcn]`` and use ``mutation="minipcn"`` to select MiniPCN explicitly. The persistent SMC, nested-sampling SMC, standalone MCMC, and additional-posterior-sample helpers also default to differential evolution. Functional nested-sampling execution -requires an explicit ``mutation="minipcn"`` or ``mutation="blackjax"``. +supports DE, MiniPCN and BlackJAX with JAX-compatible targets and transforms. The helper defaults to ``particle_transform="affine"``; configure it through ``particle_transform_kwargs`` or pass a transform object. With default ESS @@ -160,8 +160,8 @@ 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 +iterations using completed diagnostics. Place conditional steps outside the +adaptation wrappers, for example ``MutateIfResampled(mutation_step)``. Acceptance-based mutation budgets @@ -183,7 +183,10 @@ of transitions from the previous iteration's acceptance rate. Named ``mutation_n_steps`` sets the initial budget and must lie within the bounds. The mapping defaults to ``min_steps=0``, ``max_steps=1000``, and ``target_accepted_moves=5.0``. Omit it or set ``enabled=False`` to keep a fixed -budget. +budget. Acceptance-based budgets require ``max_steps <= 2**24``. + +Adaptive DE budgets also support JAX compilation. See +:doc:`../advanced_workflows/jax_support` for running a compiled sampler. Each mutation block uses a fixed budget; its acceptance rate determines the next block's budget, clipped to the bounds. Accepted moves need not be diff --git a/src/sequince/prebuilt_samplers.py b/src/sequince/prebuilt_samplers.py index 44d31796..a6befe7f 100644 --- a/src/sequince/prebuilt_samplers.py +++ b/src/sequince/prebuilt_samplers.py @@ -649,9 +649,8 @@ def make_nested_sampling_smc( Functional execution requires JAX arrays, unconditional resampling with unchanged population size, logging_frequency=0, and traceable mutation - (BlackJAX or MiniPCN). Select one explicitly with ``mutation``; the default - differential-evolution mutation is not supported for functional nested - sampling. Use callbacks for host-side logging. Initialize with + (differential evolution, BlackJAX or MiniPCN). Use callbacks for host-side + logging. Initialize with run_functional or initialize_functional before compiling iterations. Compiled schedules must use backend operations and return a scalar array; positive infinity finalizes the live tail. Python StopIteration is supported diff --git a/src/sequince/steps/__init__.py b/src/sequince/steps/__init__.py index c45fcdca..0ac4234e 100644 --- a/src/sequince/steps/__init__.py +++ b/src/sequince/steps/__init__.py @@ -33,11 +33,13 @@ DEScaleWeightPolicy, DifferentialEvolutionKernel, DifferentialEvolutionMutation, + DynamicBudgetMutation, EmceeMutation, ErynMutation, ESJDMetric, ESJDScaleWeightPolicy, FixedLengthMutation, + FunctionalMutationStepPolicy, KernelSample, MaskedGaussianRandomWalk, MetropolisBlock, @@ -45,6 +47,7 @@ MiniPCNMutation, MiniPCNRhoPolicy, MutateIfResampled, + MutationBudgetState, MutationMetric, MutationMetrics, MutationMetricsOutput, @@ -123,6 +126,7 @@ "EmceeMutation", "ErynMutation", "FixedLengthMutation", + "DynamicBudgetMutation", "MaskedGaussianRandomWalk", "KernelSample", "MetropolisHastingsMutation", @@ -136,6 +140,8 @@ "MutationTransition", "MutationMetric", "MutationMetrics", + "FunctionalMutationStepPolicy", + "MutationBudgetState", "MutationStepPolicy", "MutateIfResampled", "ProposalRejuvenation", diff --git a/src/sequince/steps/base.py b/src/sequince/steps/base.py index 5d2c9d6d..e239047c 100644 --- a/src/sequince/steps/base.py +++ b/src/sequince/steps/base.py @@ -7,6 +7,7 @@ from orng import RandomGenerator from ..array_api import namespace +from ..typing import Array from ..utils.random import resolve_rng from .context import StepContext @@ -15,6 +16,7 @@ from ..smc import SMCConfig from ..state import ParticleState + from .mutation.metrics import MutationMetrics, MutationStepState def validate_n_steps(n_steps: int) -> int: @@ -45,6 +47,52 @@ def apply_with_n_steps( ) -> tuple["ParticleState", StepContext, Any]: ... +@runtime_checkable +class DynamicBudgetMutation(Protocol): + """Functional mutation with a runtime budget and static history capacity. + + The scalar integer array budget must lie in [0, max_steps]. Initialize the + functional state/context and metadata before tracing. The returned metric + state continues an enclosing block; only its owner finalizes metrics. + ``random_state`` is the backend-native state returned by + ``orng.RandomGenerator.state()``; for JAX it is a PRNG key array. Functional + calls accept and return that state, while eager methods accept the ORNG + generator object. Configuration validation accepts an optional ``max_steps`` + override so enclosing adapters validate the effective history capacity rather + than the child's default sweep count. + """ + + @property + def metrics(self) -> MutationMetrics: ... + + def initialize_functional_metadata( + self, state: ParticleState, metadata: Mapping[str, Any] + ) -> Mapping[str, Any]: ... + + def initialize_functional_state_and_context( + self, state: ParticleState, context: StepContext + ) -> tuple[ParticleState, StepContext]: ... + + def validate_functional_configuration( + self, + config: SMCConfig, + state: ParticleState, + *, + max_steps: int | None = None, + ) -> None: ... + + def apply_dynamic_budget( + self, + state: ParticleState, + context: StepContext, + random_state: Any, + *, + n_steps: Array, + max_steps: int, + mutation_state: MutationStepState | None = None, + ) -> tuple[ParticleState, StepContext, Any, Any, MutationStepState]: ... + + class SMCStep: """Base class for steps with explicit context and output returns. @@ -81,7 +129,10 @@ def apply_functional( additional outputs. This method is intended for use in functional SMC iterations where the - random state is explicitly threaded through the computation. + random state is explicitly threaded through the computation. Pass the + backend-native state returned by ``orng.RandomGenerator.state()``; + for JAX this is a PRNG key array. An ORNG wrapper is reconstructed + internally, and its advanced state is returned to the caller. """ rng = RandomGenerator.from_xp( namespace(random_state), diff --git a/src/sequince/steps/mutation/__init__.py b/src/sequince/steps/mutation/__init__.py index cf708b05..7de7ff1c 100644 --- a/src/sequince/steps/mutation/__init__.py +++ b/src/sequince/steps/mutation/__init__.py @@ -1,6 +1,6 @@ """Mutation steps, kernels, and configuration helpers.""" -from ..base import FixedLengthMutation +from ..base import DynamicBudgetMutation, FixedLengthMutation from .adaptive import ( AcceptanceRateRhoPolicy, AdaptDEScaleWeights, @@ -10,7 +10,9 @@ AdaptMutationSteps, DEScaleWeightPolicy, ESJDScaleWeightPolicy, + FunctionalMutationStepPolicy, MiniPCNRhoPolicy, + MutationBudgetState, MutationStepPolicy, RelativeJumpDistancePolicy, ) @@ -91,6 +93,7 @@ "EmceeMutation", "ErynMutation", "FixedLengthMutation", + "DynamicBudgetMutation", "GaussianRandomWalk", "GenerativeProposal", "MUTATION_KERNELS", @@ -110,6 +113,8 @@ "MutationMetric", "MutationMetrics", "MutationStep", + "FunctionalMutationStepPolicy", + "MutationBudgetState", "MutationStepPolicy", "MutateIfResampled", "PARTICLE_TRANSFORM_KEY", diff --git a/src/sequince/steps/mutation/adaptive/__init__.py b/src/sequince/steps/mutation/adaptive/__init__.py index 3ccfce1c..1d59d672 100644 --- a/src/sequince/steps/mutation/adaptive/__init__.py +++ b/src/sequince/steps/mutation/adaptive/__init__.py @@ -3,10 +3,15 @@ from .base import AdaptiveMutationStep from .de import AdaptDEScaleWeights from .minipcn import AdaptiveMiniPCNMutation -from .policies import MutationStepPolicy, RelativeJumpDistancePolicy +from .policies import ( + FunctionalMutationStepPolicy, + MutationStepPolicy, + RelativeJumpDistancePolicy, +) from .policies.de import DEScaleWeightPolicy, ESJDScaleWeightPolicy from .policies.rho import AcceptanceRateRhoPolicy, MiniPCNRhoPolicy from .proposal import AdaptiveGaussianProposal +from .state import MutationBudgetState from .steps import AdaptMutationSteps __all__ = [ @@ -20,5 +25,7 @@ "AdaptMutationSteps", "AdaptiveGaussianProposal", "AdaptiveMiniPCNMutation", + "FunctionalMutationStepPolicy", + "MutationBudgetState", "MutationStepPolicy", ] diff --git a/src/sequince/steps/mutation/adaptive/policies/__init__.py b/src/sequince/steps/mutation/adaptive/policies/__init__.py index d53f22fe..9dca12bb 100644 --- a/src/sequince/steps/mutation/adaptive/policies/__init__.py +++ b/src/sequince/steps/mutation/adaptive/policies/__init__.py @@ -1,6 +1,6 @@ """Policies for selecting mutation budgets from completed metrics.""" -from .base import MutationStepPolicy +from .base import FunctionalMutationStepPolicy, MutationStepPolicy from .de import DEScaleWeightPolicy, ESJDScaleWeightPolicy from .rho import AcceptanceRateRhoPolicy, MiniPCNRhoPolicy from .rjd import RelativeJumpDistancePolicy @@ -9,6 +9,7 @@ "AcceptanceRateRhoPolicy", "MiniPCNRhoPolicy", "RelativeJumpDistancePolicy", + "FunctionalMutationStepPolicy", "MutationStepPolicy", "DEScaleWeightPolicy", "ESJDScaleWeightPolicy", diff --git a/src/sequince/steps/mutation/adaptive/policies/acceptance.py b/src/sequince/steps/mutation/adaptive/policies/acceptance.py index da98e2c6..b8755b6a 100644 --- a/src/sequince/steps/mutation/adaptive/policies/acceptance.py +++ b/src/sequince/steps/mutation/adaptive/policies/acceptance.py @@ -4,25 +4,21 @@ import math -from .....array_api import to_numpy +from .....array_api import asarray, namespace, to_numpy +from .....typing import Array, ArrayLike from ....base import validate_n_steps from ....context import StepContext from ...metrics import MutationMetricsOutput class AcceptanceRatePolicy: - """Target an expected number of accepted moves per particle. + """Target expected accepted moves per particle using completed counts. - Propose ``ceil(target_steps / max(acceptance, min_acceptance))`` - for the next iteration. ``min_acceptance`` (default ``1e-6``) keeps the - budget finite for zero or very small acceptance rates. Every returned - budget is clipped to the required ``min_steps`` and ``max_steps`` bounds. A block with no attempted moves - supplies no acceptance estimate, so its current budget is retained (or - increased to one when zero) to allow a subsequent measurement. - - Acceptance is estimated from the complete block's accepted and attempted - counts, including fractional expected counts from recycling algorithms. - """ + Choose ``ceil(target_steps / max(acceptance, min_acceptance))``, clipped + to configured bounds. With zero attempts, retain the current budget or + recover to one, subject to bounds. Fractional accepted counts are supported. + Both APIs divide in floating point before the ceiling and require + ``max_steps <= 2**24`` for safe integer conversion.""" def __init__( self, @@ -46,12 +42,111 @@ def __init__( self.max_steps = validate_n_steps(max_steps) if self.max_steps < self.min_steps: raise ValueError("max_steps must be >= min_steps.") + self.validate_functional_configuration() self.target_steps = float(target_steps) self.min_acceptance = float(min_acceptance) + self._functional_target = min(self.target_steps, self.max_steps) + # Bound on the host before the ceiling, including ratios that + # overflow to infinity. Positive targets always require at least one. + self._zero_acceptance_steps = self._bound( + max( + 1, + math.ceil( + min( + self.target_steps / self.min_acceptance, self.max_steps + ) + ), + ) + ) def _bound(self, steps: int) -> int: return min(max(steps, self.min_steps), self.max_steps) + def validate_functional_configuration(self) -> None: + """Require bounds exactly representable in float32 and int32.""" + if self.max_steps > 2**24: + raise ValueError( + "AcceptanceRatePolicy max_steps must be <= 2**24." + ) + + def initialise_functional( + self, *, initial_steps: Array, context: StepContext + ) -> Array: + xp = namespace(initial_steps) + return xp.clip(initial_steps, self.min_steps, self.max_steps) + + def update_functional( + self, + *, + current_steps: Array, + metrics: MutationMetricsOutput, + context: StepContext, + ) -> Array: + """Choose a bounded budget from scalar completed-block counts. + + Counts must be finite with ``0 <= accepted <= attempted``. Compiled code + checks shapes only; callers must validate values. Eager calculations use + host float64; other backend precisions may round differently.""" + return self._steps_from_counts( + current_steps=current_steps, + n_attempted=metrics.n_attempted, + n_accepted=metrics.n_accepted, + ) + + def _steps_from_counts( + self, + *, + current_steps: Array, + n_attempted: ArrayLike, + n_accepted: ArrayLike, + ) -> Array: + """Compute a bounded budget directly from scalar count inputs.""" + xp = namespace(current_steps) + accepted = asarray(n_accepted, like=current_steps) + attempted = asarray(n_attempted, like=current_steps) + if accepted.shape != () or attempted.shape != (): + raise TypeError("Mutation counts must be scalar arrays.") + dtype = xp.result_type( + accepted.dtype, + attempted.dtype, + asarray(0.0, like=current_steps).dtype, + ) + accepted = xp.astype(accepted, dtype) + attempted = xp.astype(attempted, dtype) + one = xp.ones_like(attempted) + acceptance = accepted / xp.where(attempted > 0, attempted, one) + # Cap the target on the host before materializing it: even a finite + # Python float may overflow the backend's floating dtype. + target = asarray( + self._functional_target, + like=accepted, + dtype=dtype, + ) + # ceil(target / max(rate, floor)) is the smaller of the ordinary + # decision and the zero-acceptance decision. Use the host-prepared + # safeguard even when tiny configuration values underflow together. + denominator = xp.maximum(acceptance, target / max(1, self.max_steps)) + ratio = target / xp.where(denominator > 0, denominator, one) + safeguard = asarray( + self._zero_acceptance_steps, like=accepted, dtype=dtype + ) + proposed = xp.where( + acceptance > 0, + xp.minimum(xp.ceil(ratio), safeguard), + safeguard, + ) + proposed = xp.clip( + xp.maximum(proposed, one), self.min_steps, self.max_steps + ) + # Bound before conversion to prevent overflow in the integer cast. + proposed = xp.astype(proposed, current_steps.dtype) + recovery = xp.clip( + xp.maximum(current_steps, xp.ones_like(current_steps)), + self.min_steps, + self.max_steps, + ) + return xp.where(attempted > 0, proposed, recovery) + def initialise(self, *, initial_steps: int, context: StepContext) -> int: return self._bound(validate_n_steps(initial_steps)) @@ -79,15 +174,15 @@ def update( attempted, accepted = counts if accepted > attempted: raise ValueError("n_accepted must not exceed n_attempted.") - if attempted == 0: - return self._bound(max(1, current_steps)) - acceptance = max(accepted / attempted, self.min_acceptance) - # Integer ratios avoid overflow even for very large finite targets. - numerator, denominator = self.target_steps.as_integer_ratio() - a_numerator, a_denominator = acceptance.as_integer_ratio() - numerator *= a_denominator - denominator *= a_numerator - return self._bound((numerator + denominator - 1) // denominator) + return int( + self._steps_from_counts( + current_steps=asarray( + self._bound(current_steps), dtype="int32" + ), + n_attempted=asarray(attempted), + n_accepted=asarray(accepted), + ) + ) __all__ = ["AcceptanceRatePolicy"] diff --git a/src/sequince/steps/mutation/adaptive/policies/base.py b/src/sequince/steps/mutation/adaptive/policies/base.py index e938615b..023fb2bc 100644 --- a/src/sequince/steps/mutation/adaptive/policies/base.py +++ b/src/sequince/steps/mutation/adaptive/policies/base.py @@ -2,18 +2,15 @@ from __future__ import annotations -from typing import Protocol +from typing import Protocol, runtime_checkable +from .....typing import Array from ....context import StepContext from ...metrics import MutationMetricsOutput class MutationStepPolicy(Protocol): - """Choose mutation budgets using completed, iteration-level metrics. - - Policies are called only at mutation-block boundaries. In particular, they - never receive intermediate mutation states or metrics. - """ + """Choose mutation budgets at completed-block boundaries.""" def initialise(self, *, initial_steps: int, context: StepContext) -> int: """Choose the budget for the first adaptive iteration.""" @@ -30,4 +27,34 @@ def update( ... -__all__ = ["MutationStepPolicy"] +@runtime_checkable +class FunctionalMutationStepPolicy(MutationStepPolicy, Protocol): + """Pure, traceable extension of the eager budget policy. + + Return scalar integer arrays matching the input budget's dtype and device. + Do not mutate the policy or inputs, convert arrays to host values, or + change carry structure. Methods return decisions only; validate static + configuration on the host.""" + + def validate_functional_configuration(self) -> None: + """Reject static settings unsupported by functional decisions.""" + ... + + def initialise_functional( + self, *, initial_steps: Array, context: StepContext + ) -> Array: + """Choose the first budget without modifying any inputs.""" + ... + + def update_functional( + self, + *, + current_steps: Array, + metrics: MutationMetricsOutput, + context: StepContext, + ) -> Array: + """Choose a pending budget from completed-block metrics.""" + ... + + +__all__ = ["MutationStepPolicy", "FunctionalMutationStepPolicy"] diff --git a/src/sequince/steps/mutation/adaptive/policies/fixed.py b/src/sequince/steps/mutation/adaptive/policies/fixed.py index 9a23b5b3..a6d2ddcb 100644 --- a/src/sequince/steps/mutation/adaptive/policies/fixed.py +++ b/src/sequince/steps/mutation/adaptive/policies/fixed.py @@ -2,26 +2,39 @@ from __future__ import annotations +from typing import TypeVar + from ....context import StepContext from ...metrics import MutationMetricsOutput +_Budget = TypeVar("_Budget") + class FixedMutationStepPolicy: """Keep the mutation budget fixed at its current value.""" - def initialise(self, *, initial_steps: int, context: StepContext) -> int: + def validate_functional_configuration(self) -> None: + """No additional static configuration is required.""" + + def initialise( + self, *, initial_steps: _Budget, context: StepContext + ) -> _Budget: del context return initial_steps def update( self, *, - current_steps: int, + current_steps: _Budget, metrics: MutationMetricsOutput, context: StepContext, - ) -> int: + ) -> _Budget: del metrics, context return current_steps + # Fixed decisions have identical scalar and array semantics. + initialise_functional = initialise + update_functional = update + __all__ = ["FixedMutationStepPolicy"] diff --git a/src/sequince/steps/mutation/adaptive/state.py b/src/sequince/steps/mutation/adaptive/state.py new file mode 100644 index 00000000..e6322a8a --- /dev/null +++ b/src/sequince/steps/mutation/adaptive/state.py @@ -0,0 +1,39 @@ +"""Complete budget state shared by eager and functional adaptation.""" + +from dataclasses import dataclass +from typing import Generic, Self, TypeVar + +from ....utils.pytrees import pytree_dataclass + +_Scalar = TypeVar("_Scalar") + + +@pytree_dataclass( + data_fields=( + "current_iteration", + "current_n_steps", + "next_n_steps", + "last_updated_iteration", + ) +) +@dataclass(frozen=True) +class MutationBudgetState(Generic[_Scalar]): + """Immutable current and pending budgets with iteration markers. + + Eager fields are host integers; functional fields are scalar int32 arrays. + Both budgets initially equal ``initial_steps``; unset iterations use -1.""" + + current_iteration: _Scalar + current_n_steps: _Scalar + next_n_steps: _Scalar + last_updated_iteration: _Scalar + + @classmethod + def initial(cls, initial_steps: _Scalar, unset_iteration: _Scalar) -> Self: + """Allocate both budget slots and mark both iterations as unset.""" + return cls( + unset_iteration, initial_steps, initial_steps, unset_iteration + ) + + +__all__ = ["MutationBudgetState"] diff --git a/src/sequince/steps/mutation/adaptive/steps.py b/src/sequince/steps/mutation/adaptive/steps.py index 7898e7f3..4a9ad049 100644 --- a/src/sequince/steps/mutation/adaptive/steps.py +++ b/src/sequince/steps/mutation/adaptive/steps.py @@ -2,33 +2,43 @@ from __future__ import annotations -from collections.abc import Mapping +from collections.abc import Callable, Mapping +from dataclasses import asdict, fields, replace from numbers import Integral -from typing import Any +from typing import TYPE_CHECKING, Any, TypeVar -from ...base import FixedLengthMutation, validate_n_steps +from acai import cond + +from ....array_api import asarray, namespace +from ....typing import Array +from ...base import ( + DynamicBudgetMutation, + FixedLengthMutation, + validate_n_steps, +) from ...context import StepContext from ..metrics import MutationMetricsOutput +from ..metrics.base import with_metrics from .base import AdaptiveMutationStep from .policies import MutationStepPolicy +from .policies.base import FunctionalMutationStepPolicy from .policies.fixed import FixedMutationStepPolicy +from .state import MutationBudgetState +if TYPE_CHECKING: + from ....smc import SMCConfig + from ....state import ParticleState -class AdaptMutationSteps(AdaptiveMutationStep): - """Adapt a fixed-length mutation budget between SMC iterations. - Conditional on the completed SMC history before iteration ``t``, the - mutation budget is chosen and frozen before mutation begins. The wrapped - mutation then executes that complete fixed-length block. Its final - :class:`MutationMetricsOutput` may determine the budget for iteration - ``t + 1``, but cannot change the current block. Repeated calls with the same - :attr:`StepContext.iteration` reuse the frozen budget and update the policy - at most once. +_Scalar = TypeVar("_Scalar", int, Array) + + +class AdaptMutationSteps(AdaptiveMutationStep): + """Adapt fixed mutation budgets using completed SMC history. - This wrapper deliberately does not implement trajectory-dependent stopping. - Budget splitting across fixed rounds (for example, in - ``RepeatedMutationStep``) remains the responsibility of the wrapped mutation. - """ + Freeze each iteration's budget before mutation. Completed-block metrics + propose the next budget; repeated calls reuse the frozen budget and + update the policy at most once per iteration.""" def __init__( self, @@ -38,6 +48,7 @@ def __init__( initial_steps: int, min_steps: int, max_steps: int, + metadata_key: str = "mutation_budget", ) -> None: if not isinstance(mutation, FixedLengthMutation): raise TypeError( @@ -63,49 +74,275 @@ def __init__( raise TypeError("policy must implement initialise() and update().") super().__init__(mutation) + if not isinstance(metadata_key, str) or not metadata_key: + raise ValueError("metadata_key must be a nonempty string.") + self._metadata_key = metadata_key self.policy = resolved_policy - self._policy_initialised = False - self._current_iteration: int | None = None - self._current_n_steps: int | None = None - self._next_n_steps: int | None = None - self._last_updated_iteration: int | None = None + self._budget = MutationBudgetState[int].initial( + self._initial_steps, -1 + ) @property - def current_n_steps(self) -> int | None: - """The budget frozen for the current or most recent iteration.""" - return self._current_n_steps + def metadata_key(self) -> str: + """Stable carry identity; use distinct keys for multiple adapters.""" + return self._metadata_key + + def _functional_policy(self) -> FunctionalMutationStepPolicy: + if not isinstance(self.policy, FunctionalMutationStepPolicy): + raise NotImplementedError( + "Policy must implement FunctionalMutationStepPolicy for " + "functional budget operations. Eager policies remain supported." + ) + return self.policy + + def initialize_functional_metadata( + self, state: ParticleState, metadata: Mapping[str, Any] + ) -> Mapping[str, Any]: + """Allocate a scalar int32 carry before compilation, preserving resumes. + + Requires ``max_steps <= 2**24``. Resume with the same metadata key and + static configuration; eager state is independent.""" + if isinstance(self.mutation, DynamicBudgetMutation): + metadata = self.mutation.initialize_functional_metadata( + state, metadata + ) + policy = self._functional_policy() + policy.validate_functional_configuration() + if self._max_steps > 2**24: + raise ValueError("Functional budget max_steps must be <= 2**24.") + if self.metadata_key in metadata: + carry = metadata[self.metadata_key] + if not isinstance(carry, MutationBudgetState): + raise TypeError("Budget metadata must be MutationBudgetState.") + for field in fields(carry): + value = getattr(carry, field.name) + if ( + getattr(value, "shape", None) != () + or value.dtype != namespace(value).int32 + ): + raise TypeError( + "Budget carry leaves must be scalar int32." + ) + return metadata + like = state.log_weights + + def scalar(value: int) -> Array: + return asarray(value, like=like, dtype="int32") + + carry = MutationBudgetState[Array].initial( + scalar(self._initial_steps), scalar(-1) + ) + return {**metadata, self.metadata_key: carry} + + def _budget_state( + self, context: StepContext + ) -> MutationBudgetState[Array]: + carry = context.metadata.get(self.metadata_key) + if not isinstance(carry, MutationBudgetState): + raise TypeError( + "Initialize functional budget metadata before compilation." + ) + return carry + + def prepare_budget_functional( + self, context: StepContext + ) -> tuple[StepContext, Array]: + """Freeze the budget before a block, promoting a pending decision. + + Parameters + ---------- + context : StepContext + Initialized context with a nonnegative scalar int32 iteration. + + Returns + ------- + context : StepContext + New context containing the prepared carry. + n_steps : array, shape () + Frozen int32 budget, reused for every call in this iteration. + """ + policy = self._functional_policy() + carry = self._budget_state(context) + xp = namespace(carry.current_n_steps) + iteration = asarray( + context.iteration, like=carry.current_iteration, dtype="int32" + ) + + prepared = self._prepare_budget( + carry, + iteration, + initialise=lambda: policy.initialise_functional( + initial_steps=carry.current_n_steps, context=context + ), + xp=xp, + ) + return ( + context.with_metadata(**{self.metadata_key: prepared}), + prepared.current_n_steps, + ) + + def update_budget_functional( + self, metrics: MutationMetricsOutput, context: StepContext + ) -> StepContext: + """Store a pending budget from completed metrics, at most once. + + Parameters + ---------- + metrics : MutationMetricsOutput + Final metrics for the complete mutation block. + context : StepContext + Prepared context identifying that block's iteration. + + Returns + ------- + StepContext + New context with a pending budget; the current budget is unchanged. + Compiled runtime values are not validated.""" + policy = self._functional_policy() + carry = self._budget_state(context) + xp = namespace(carry.current_n_steps) + + updated = self._update_budget( + carry, + propose=lambda: policy.update_functional( + current_steps=carry.current_n_steps, + metrics=metrics, + context=context, + ), + xp=xp, + ) + return context.with_metadata(**{self.metadata_key: updated}) + + def _dynamic_child(self) -> DynamicBudgetMutation: + if not isinstance(self.mutation, DynamicBudgetMutation): + raise NotImplementedError( + "Child supports eager execution only; functional execution requires DynamicBudgetMutation." + ) + return self.mutation + + def validate_functional_configuration( + self, config: SMCConfig, state: ParticleState + ) -> None: + self._dynamic_child().validate_functional_configuration( + config, state, max_steps=self._max_steps + ) + + def initialize_functional_state_and_context( + self, state: ParticleState, context: StepContext + ) -> tuple[ParticleState, StepContext]: + return self._dynamic_child().initialize_functional_state_and_context( + state, context + ) + + def apply_functional( + self, state: ParticleState, context: StepContext, random_state: Any + ) -> tuple[ParticleState, StepContext, Any, Any]: + """Execute the frozen budget and adapt from this completed block only.""" + child = self._dynamic_child() + context, n_steps = self.prepare_budget_functional(context) + state, context, random_state, output, metric_state = ( + child.apply_dynamic_budget( + state, + context, + random_state, + n_steps=n_steps, + max_steps=self._max_steps, + ) + ) + metrics = child.metrics.result(metric_state, context) + output = with_metrics(output, metrics) + context = self.update_budget_functional(metrics, context) + return state, context, random_state, output @property - def next_n_steps(self) -> int | None: - """The budget proposed for the next outer iteration, if known.""" - return self._next_n_steps + def current_n_steps(self) -> int: + """The frozen budget, or initial_steps before the first preparation.""" + return self._budget.current_n_steps - def _bound_policy_decision(self, value: int) -> int: + @property + def next_n_steps(self) -> int: + """The pending budget, initially equal to initial_steps.""" + return self._budget.next_n_steps + + def _bound_policy_decision( + self, value: int | Array, *, xp: Any | None = None + ) -> int | Array: + if xp is not None: + return xp.clip(value, self._min_steps, self._max_steps) if isinstance(value, bool) or not isinstance(value, Integral): raise TypeError("Mutation policy decisions must be integers.") return min(max(int(value), self._min_steps), self._max_steps) - def _freeze_budget(self, context: StepContext) -> int: - if self._current_iteration == context.iteration: - if self._current_n_steps is None: # pragma: no cover - state guard - raise RuntimeError("The current mutation budget is missing.") - return self._current_n_steps - - if not self._policy_initialised: - proposed = self.policy.initialise( - initial_steps=self._initial_steps, - context=context, + def _prepare_budget( + self, + carry: MutationBudgetState[_Scalar], + iteration: _Scalar, + *, + initialise: Callable[[], _Scalar], + xp: Any | None = None, + ) -> MutationBudgetState[_Scalar]: + """Choose once, clip, and freeze; promote pending on advancement.""" + + control_xp = namespace() if xp is None else xp + + def prepare(_: None) -> MutationBudgetState[_Scalar]: + budget = cond( + carry.current_iteration >= 0, + lambda _: carry.next_n_steps, + lambda _: initialise(), + None, + xp=control_xp, ) - else: - if self._next_n_steps is None: # pragma: no cover - state guard - raise RuntimeError("The next mutation budget is missing.") - proposed = self._next_n_steps + budget = self._bound_policy_decision(budget, xp=xp) + return replace( + carry, + current_iteration=iteration, + current_n_steps=budget, + next_n_steps=budget, + ) + + return cond( + carry.current_iteration == iteration, + lambda _: carry, + prepare, + None, + xp=control_xp, + ) + + def _update_budget( + self, + carry: MutationBudgetState[_Scalar], + *, + propose: Callable[[], _Scalar], + xp: Any | None = None, + ) -> MutationBudgetState[_Scalar]: + """Accept the first completed block's bounded pending decision.""" - frozen = self._bound_policy_decision(proposed) - self._policy_initialised = True - self._current_iteration = context.iteration - self._current_n_steps = frozen - return frozen + def update(_: None) -> MutationBudgetState[_Scalar]: + return replace( + carry, + next_n_steps=self._bound_policy_decision(propose(), xp=xp), + last_updated_iteration=carry.current_iteration, + ) + + return cond( + (carry.current_iteration >= 0) + & (carry.last_updated_iteration != carry.current_iteration), + update, + lambda _: carry, + None, + xp=namespace() if xp is None else xp, + ) + + def _freeze_budget(self, context: StepContext) -> int: + self._budget = self._prepare_budget( + self._budget, + context.iteration, + initialise=lambda: self.policy.initialise( + initial_steps=self._budget.current_n_steps, context=context + ), + ) + return self._budget.current_n_steps def _prepare_mutation( self, @@ -122,93 +359,58 @@ def _adapt( initial_context: StepContext, n_steps: int | None, ) -> StepContext: - iteration = initial_context.iteration - if self._last_updated_iteration != iteration: - assert n_steps is not None - proposed = self.policy.update( - current_steps=n_steps, + del initial_context, n_steps + carry = self._budget + self._budget = self._update_budget( + carry, + propose=lambda: self.policy.update( + current_steps=carry.current_n_steps, metrics=metrics, context=context, - ) - self._next_n_steps = self._bound_policy_decision(proposed) - self._last_updated_iteration = iteration + ), + ) return context def state_dict(self) -> dict[str, Any]: - """Return the frozen/current decision and nested mutable state.""" + """Return the complete eager budget carry and nested mutable state.""" return { - "policy_initialised": self._policy_initialised, - "current_iteration": self._current_iteration, - "current_n_steps": self._current_n_steps, - "next_n_steps": self._next_n_steps, - "last_updated_iteration": self._last_updated_iteration, + "budget": asdict(self._budget), **super().state_dict(), "policy": self._nested_state(self.policy, "Policy"), } - @staticmethod - def _optional_integer(value: Any, name: str) -> int | None: - if value is None: - return None - if isinstance(value, bool) or not isinstance(value, Integral): - raise TypeError( - f"AdaptMutationSteps state '{name}' must be an integer." - ) - return int(value) - def load_state_dict(self, state: Mapping[str, Any]) -> None: - """Restore an adaptive decision without consulting the policy again.""" - required = { - "policy_initialised", - "current_iteration", - "current_n_steps", - "next_n_steps", - "last_updated_iteration", - "mutation", - "policy", - } - missing = required.difference(state) - if missing: + """Restore the eager budget and nested state from the current schema. + + Legacy checkpoints are not supported.""" + required = {"budget", "mutation", "policy"} + if missing := required.difference(state): raise ValueError( "AdaptMutationSteps state is missing required keys: " + ", ".join(sorted(missing)) ) - initialised = state["policy_initialised"] - if not isinstance(initialised, bool): - raise TypeError( - "AdaptMutationSteps state 'policy_initialised' must be a boolean." + budget = state["budget"] + names = {field.name for field in fields(MutationBudgetState)} + if not isinstance(budget, Mapping) or set(budget) != names: + raise ValueError( + "Budget state must contain all four carry fields." + ) + values = {} + for name, value in budget.items(): + if isinstance(value, bool) or not isinstance(value, Integral): + raise TypeError(f"Budget state '{name}' must be an integer.") + values[name] = int(value) + carry = MutationBudgetState[int](**values) + for value in (carry.current_n_steps, carry.next_n_steps): + if not self._min_steps <= value <= self._max_steps: + raise ValueError("Budget state is outside configured bounds.") + if not -1 <= carry.last_updated_iteration <= carry.current_iteration: + raise ValueError( + "Budget state iteration markers are inconsistent." ) - current_iteration = self._optional_integer( - state["current_iteration"], "current_iteration" - ) - current_n_steps = self._optional_integer( - state["current_n_steps"], "current_n_steps" - ) - next_n_steps = self._optional_integer( - state["next_n_steps"], "next_n_steps" - ) - last_updated_iteration = self._optional_integer( - state["last_updated_iteration"], "last_updated_iteration" - ) - for name, value in ( - ("current_n_steps", current_n_steps), - ("next_n_steps", next_n_steps), - ): - if ( - value is not None - and not self._min_steps <= value <= self._max_steps - ): - raise ValueError( - f"AdaptMutationSteps state '{name}' is outside configured bounds." - ) - super().load_state_dict(state) self._load_nested_state(self.policy, state["policy"], "policy") - self._policy_initialised = initialised - self._current_iteration = current_iteration - self._current_n_steps = current_n_steps - self._next_n_steps = next_n_steps - self._last_updated_iteration = last_updated_iteration + self._budget = carry __all__ = ["AdaptMutationSteps"] diff --git a/src/sequince/steps/mutation/metrics/base.py b/src/sequince/steps/mutation/metrics/base.py index bdcd49ab..adaf4bbd 100644 --- a/src/sequince/steps/mutation/metrics/base.py +++ b/src/sequince/steps/mutation/metrics/base.py @@ -4,7 +4,7 @@ from collections.abc import Iterator, Sequence from dataclasses import dataclass, replace -from typing import Any, Protocol +from typing import Any, Protocol, overload from ....array_api import asarray, namespace from ....typing import Array @@ -158,6 +158,14 @@ def update( + xp.sum(asarray(accepted, xp=xp)), ) + @overload + def result( + self, metric_state: MutationStepState, context: StepContext + ) -> MutationMetricsOutput: ... + + @overload + def result(self, metric_state: None, context: StepContext) -> None: ... + def result( self, metric_state: MutationStepState | None, diff --git a/src/sequince/steps/mutation/metropolis.py b/src/sequince/steps/mutation/metropolis.py index de105c6b..0c78dc38 100644 --- a/src/sequince/steps/mutation/metropolis.py +++ b/src/sequince/steps/mutation/metropolis.py @@ -7,7 +7,9 @@ import array_api_extra as xpx import optree +from acai import cond, fori_loop from array_api_compat import device as get_device +from orng import RandomGenerator from ...array_api import asarray, namespace, to_numpy from ...target import EvaluationCounts @@ -33,10 +35,10 @@ MutationStepState, MutationTransition, ) +from .metrics.base import with_metrics if TYPE_CHECKING: - from orng import RandomGenerator - + from ...smc import SMCConfig from ...state import ParticleState from ...target import Target, TargetEvaluation @@ -553,6 +555,119 @@ def _apply_half( proposal.auxiliary, ) + def _sweep( + self, + current: Array, + current_log_prob: Array, + current_evaluation: TargetEvaluation | None, + mutation_state: MutationStepState, + *, + kernel: ComplementaryEnsembleKernel, + transform: ParticleTransform | None, + transform_auxiliary: Any, + context: StepContext, + rng: RandomGenerator, + ) -> tuple[ + Array, + Array, + TargetEvaluation | None, + MutationStepState, + EvaluationCounts, + Array, + Array, + ]: + """Execute one complete sweep, shared by eager and dynamic execution.""" + xp = namespace(current) + n_particles = current.shape[0] + previous = current + accepted_population = xp.zeros_like(current_log_prob, dtype=xp.bool) + group_a, group_b = self._split_indices( + n_particles, + rng, + ) + complementary_a = current[group_b] + ( + current, + current_log_prob, + current_evaluation, + counts_a, + accepted_a, + accepted_mask_a, + auxiliary_a, + ) = self._apply_half( + current, + current_log_prob, + current_evaluation, + group_a, + complementary_a, + kernel, + transform, + transform_auxiliary, + context, + rng, + ) + counts = counts_a + accepted_population = xpx.at(accepted_population, group_a).set( + accepted_mask_a, copy=True, xp=xp + ) + complementary_b = current[group_a] + ( + current, + current_log_prob, + current_evaluation, + counts_b, + accepted_b, + accepted_mask_b, + auxiliary_b, + ) = self._apply_half( + current, + current_log_prob, + current_evaluation, + group_b, + complementary_b, + kernel, + transform, + transform_auxiliary, + context, + rng, + ) + counts = counts + counts_b + accepted_population = xpx.at(accepted_population, group_b).set( + accepted_mask_b, copy=True, xp=xp + ) + transition = None + if self.metrics.needs_transition: + # Restore particle-aligned auxiliary to population order. + order = xp.argsort(xp.concat((group_a, group_b))) + transition = MutationTransition( + displacement=current - previous, + kernel_auxiliary=optree.tree_map( + lambda a, b: namespace(a, b).concat((a, b), axis=0)[order], + auxiliary_a, + auxiliary_b, + namespace=OPTREE_NAMESPACE, + ), + ) + accepted_sweep = accepted_a + accepted_b + mutation_state = self.metrics.update( + mutation_state, + current, + accepted_population, + context, + transition=transition, + ) + return ( + current, + current_log_prob, + current_evaluation, + mutation_state, + counts, + accepted_sweep, + xp.stack( + (accepted_a / group_a.shape[0], accepted_b / group_b.shape[0]) + ), + ) + def apply( self, state: ParticleState, @@ -563,6 +678,87 @@ def apply( state, context, rng, n_steps=self._n_steps ) + def _prepare_block( + self, + state: ParticleState, + context: StepContext, + rng: RandomGenerator, + mutation_state: MutationStepState | None, + ) -> tuple[ + Array, + ParticleTransform | None, + Any, + StepContext, + MutationStepState, + Array, + TargetEvaluation | None, + EvaluationCounts, + ]: + """Prepare coordinates, metrics and starting density for a segment.""" + transform, context = self._prepare_transform( + state.particles, context, rng=rng + ) + current, auxiliary = self._forward_transform( + state.particles, transform, context, rng=rng + ) + current = asarray(current, like=state.particles) + metrics = self._prepare_block_metrics( + current, state, context, mutation_state + ) + if current.shape[0] < 2: + raise ValueError( + "A red-blue update requires at least two particles." + ) + log_prob, evaluation, counts = self._evaluate_log_prob( + current, transform, context, state.evaluation, auxiliary=auxiliary + ) + return ( + current, + transform, + auxiliary, + context, + metrics, + log_prob, + evaluation, + counts, + ) + + def _prepare_block_metrics( + self, + current: Array, + state: ParticleState, + context: StepContext, + mutation_state: MutationStepState | None, + ) -> MutationStepState: + """Start metrics or continue the enclosing block in current coordinates.""" + return ( + self.metrics.initialize(current, state.log_weights, context) + if mutation_state is None + else self.metrics.prepare(mutation_state, current, context) + ) + + def _finish_block( + self, + state: ParticleState, + context: StepContext, + current: Array, + evaluation: TargetEvaluation | None, + counts: EvaluationCounts, + acceptance: Array | float, + transform: ParticleTransform | None, + auxiliary: Any, + ) -> tuple[ParticleState, StepContext]: + """Return to physical coordinates and record completed segment work.""" + particles, _ = self._inverse_transform( + current, transform, context, auxiliary=auxiliary + ) + context = context.add_evaluation_counts(counts).with_metadata( + metropolis_hastings_acceptance=acceptance + ) + return state.replace_particles( + particles, evaluation=evaluation + ), context + def apply_with_mutation_state( self, state: ParticleState, @@ -578,14 +774,8 @@ def apply_with_mutation_state( n_steps = validate_n_steps(n_steps) if n_steps == 0: xp = namespace(state.particles) - mutation_state = ( - self.metrics.initialize( - state.particles, state.log_weights, context - ) - if mutation_state is None - else self.metrics.prepare( - mutation_state, state.particles, context - ) + mutation_state = self._prepare_block_metrics( + state.particles, state, context, mutation_state ) empty_chain = ( xp.empty( @@ -609,143 +799,49 @@ def apply_with_mutation_state( mutation_state, ) xp = namespace(state.particles) - transform, context = self._prepare_transform( - state.particles, - context, - rng=rng, - ) - current, transform_auxiliary = self._forward_transform( - state.particles, + ( + current, transform, + transform_auxiliary, context, - rng=rng, - ) - current = asarray(current, xp=xp, like=state.particles) - n_particles = current.shape[0] - mutation_state = ( - self.metrics.initialize(current, state.log_weights, context) - if mutation_state is None - else self.metrics.prepare(mutation_state, current, context) - ) - if n_particles < 2: - raise ValueError( - "A red-blue update requires at least two particles." - ) - ( + mutation_state, current_log_prob, current_evaluation, counts, - ) = self._evaluate_log_prob( - current, - transform, - context, - state.evaluation, - auxiliary=transform_auxiliary, - ) + ) = self._prepare_block(state, context, rng, mutation_state) + n_particles = current.shape[0] accepted_total = 0 acceptance_by_step: list[float] = [] acceptance_by_half: list[tuple[float, float]] = [] chain: list[Array] = [] for _ in range(n_steps): - previous = current - accepted_population = xp.zeros_like( - current_log_prob, dtype=xp.bool - ) - group_a, group_b = self._split_indices( - n_particles, - rng, - ) - complementary_a = current[group_b] ( current, current_log_prob, current_evaluation, - counts_a, - accepted_a, - accepted_mask_a, - auxiliary_a, - ) = self._apply_half( + mutation_state, + sweep_counts, + accepted_sweep, + halves, + ) = self._sweep( current, current_log_prob, current_evaluation, - group_a, - complementary_a, - kernel, - transform, - transform_auxiliary, - context, - rng, - ) - counts = counts + counts_a - accepted_population = xpx.at(accepted_population, group_a).set( - accepted_mask_a, copy=True, xp=xp + mutation_state, + kernel=kernel, + transform=transform, + transform_auxiliary=transform_auxiliary, + context=context, + rng=rng, ) - complementary_b = current[group_a] - ( - current, - current_log_prob, - current_evaluation, - counts_b, - accepted_b, - accepted_mask_b, - auxiliary_b, - ) = self._apply_half( - current, - current_log_prob, - current_evaluation, - group_b, - complementary_b, - kernel, - transform, - transform_auxiliary, - context, - rng, - ) - counts = counts + counts_b - accepted_population = xpx.at(accepted_population, group_b).set( - accepted_mask_b, copy=True, xp=xp - ) - transition = None - if self.metrics.needs_transition: - # Restore particle-aligned auxiliary to population order. - order = xp.argsort(xp.concat((group_a, group_b))) - transition = MutationTransition( - displacement=current - previous, - kernel_auxiliary=optree.tree_map( - lambda a, b: namespace(a, b).concat((a, b), axis=0)[ - order - ], - auxiliary_a, - auxiliary_b, - namespace=OPTREE_NAMESPACE, - ), - ) - accepted_sweep = accepted_a + accepted_b + counts = counts + sweep_counts accepted_total += accepted_sweep acceptance_by_step.append(accepted_sweep / n_particles) - acceptance_by_half.append( - ( - accepted_a / group_a.shape[0], - accepted_b / group_b.shape[0], - ) - ) - mutation_state = self.metrics.update( - mutation_state, - current, - accepted_population, - context, - transition=transition, - ) + acceptance_by_half.append((halves[0], halves[1])) if self._store_chains: chain.append(current) - new_particles, _ = self._inverse_transform( - current, - transform, - context, - auxiliary=transform_auxiliary, - ) acceptance = accepted_total / (n_particles * n_steps) stored_chain = None if self._store_chains: @@ -756,8 +852,15 @@ def apply_with_mutation_state( auxiliary=transform_auxiliary, like=state.particles, ) - context = context.add_evaluation_counts(counts).with_metadata( - metropolis_hastings_acceptance=acceptance + state, context = self._finish_block( + state, + context, + current, + current_evaluation, + counts, + acceptance, + transform, + transform_auxiliary, ) logger.debug( "RedBlueMetropolisHastingsMutation completed: acceptance=%.3f " @@ -773,10 +876,7 @@ def apply_with_mutation_state( "metrics": None, } return ( - state.replace_particles( - new_particles, - evaluation=current_evaluation, - ), + state, context, output, mutation_state, @@ -860,3 +960,277 @@ def __init__( store_chains=store_chains, metrics=metrics, ) + + def _validate_dynamic_budget( + self, state: ParticleState, *, max_steps: int + ) -> None: + """Validate static dynamic-execution requirements before compilation.""" + validate_n_steps(max_steps) + if state.particles.ndim != 2 or state.particles.shape[0] < 4: + raise ValueError( + "Functional DE requires a 2D population of at least four particles." + ) + if callable(self._transform_refit): + raise NotImplementedError( + "Callable transform_refit is not functional." + ) + + def validate_functional_configuration( + self, + config: SMCConfig, + state: ParticleState, + *, + max_steps: int | None = None, + ) -> None: + """Validate the effective capacity supplied by an enclosing adapter.""" + self._validate_dynamic_budget( + state, max_steps=self.n_steps if max_steps is None else max_steps + ) + + def apply_functional( + self, state: ParticleState, context: StepContext, random_state: Any + ) -> tuple[ParticleState, StepContext, Any, Any]: + state, context, random_state, output, metric_state = ( + self.apply_dynamic_budget( + state, + context, + random_state, + n_steps=namespace(state.particles).asarray( + self.n_steps, dtype="int32" + ), + max_steps=self.n_steps, + ) + ) + return ( + state, + context, + random_state, + with_metrics(output, self.metrics.result(metric_state, context)), + ) + + def apply_dynamic_budget( + self, + state: ParticleState, + context: StepContext, + random_state: Any, + *, + n_steps: Array, + max_steps: int, + mutation_state: MutationStepState | None = None, + ) -> tuple[ + ParticleState, StepContext, Any, dict[str, Any], MutationStepState + ]: + """Run complete sweeps with fixed-capacity diagnostics under JAX. + + Parameters + ---------- + state : ParticleState + Initialized particles with shape (n_particles, n_dimensions), + floating dtype, and any shape-complete target cache. + context : StepContext + Initialized acceptance and optional functional transform metadata. + random_state : object + Backend-native state returned by ``orng.RandomGenerator.state()``, + threaded explicitly through executed sweeps. For JAX this is a + PRNG key array. Pass the state rather than the ORNG generator + object; ORNG wrappers are reconstructed internally for draws. + n_steps : array, shape () + Integer budget in [0, max_steps]. Bounds are a caller precondition; + compiled runtime values are not checked. + max_steps : int + Static non-negative capacity bounding the executed sweep count. + mutation_state : MutationStepState or None + Continuing block metrics, or None to initialize a new block. + + Returns + ------- + state : ParticleState + Updated original-coordinate particles and target cache. + context : StepContext + Updated transform, acceptance metadata and evaluation counters. + random_state : object + Advanced backend-native ORNG state, unchanged when the budget is + zero. For JAX this is a PRNG key array. + output : dict + ``steps`` is the scalar executed count. Only this many leading rows + of ``acceptance_by_step`` (max_steps,) and ``acceptance_by_half`` + (max_steps, 2) are valid. Optional ``chain`` has shape (max_steps, + n_particles, n_dimensions) in original coordinates. Unused rows are + zero. No chain buffer is allocated when storage is disabled. + mutation_state : MutationStepState + Accumulated metrics, independent of padded histories, for the block + owner to finalize once. ``output["metrics"]`` remains None. + + Notes + ----- + Call functional metadata and state/context initialization before JIT. + One-time initialization may fit transforms and populate target caches. + Block execution with a zero budget performs no transform preparation, + target evaluation or RNG draw. Transforms remain fixed per segment. + """ + self._validate_dynamic_budget(state, max_steps=max_steps) + xp = namespace(state.particles) + if n_steps.shape != () or not xp.isdtype(n_steps.dtype, "integral"): + raise TypeError("n_steps must be a scalar integer array.") + zeros = xp.zeros((max_steps,), dtype=state.particles.dtype) + halves = xp.zeros((max_steps, 2), dtype=state.particles.dtype) + chain = ( + xp.zeros( + (max_steps, *state.particles.shape), + dtype=state.particles.dtype, + ) + if self.store_chains + else None + ) + + def execute(_: None) -> tuple[Any, ...]: + rng = RandomGenerator.from_xp(xp, generator=random_state) + ( + current, + transform, + auxiliary, + prepared, + metrics, + log_prob, + evaluation, + counts, + ) = self._prepare_block(state, context, rng, mutation_state) + accepted_before = metrics.n_accepted + + def sweep(index: Array, carry: tuple[Any, ...]) -> tuple[Any, ...]: + ( + current, + log_prob, + evaluation, + metrics, + counts, + key, + history, + half_history, + chains, + ) = carry + rng = RandomGenerator.from_xp(xp, generator=key) + ( + current, + log_prob, + evaluation, + metrics, + work, + acceptance, + half, + ) = self._sweep( + current, + log_prob, + evaluation, + metrics, + kernel=self.kernel, + transform=transform, + transform_auxiliary=auxiliary, + context=prepared, + rng=rng, + ) + if self.store_chains: + original, _ = self._inverse_transform( + current, transform, prepared, auxiliary=auxiliary + ) + chains = chains.at[index].set(original) + return ( + current, + log_prob, + evaluation, + metrics, + counts + work, + rng.state(), + history.at[index].set(acceptance / current.shape[0]), + half_history.at[index].set(half), + chains, + ) + + ( + current, + _, + evaluation, + metrics, + counts, + key, + history, + half_history, + chains, + ) = fori_loop( + 0, + n_steps, + sweep, + ( + current, + log_prob, + evaluation, + metrics, + counts, + rng.state(), + zeros, + halves, + chain, + ), + xp=xp, + ) + acceptance = xp.astype( + metrics.n_accepted - accepted_before, current.dtype + ) / (current.shape[0] * n_steps) + updated, prepared = self._finish_block( + state, + prepared, + current, + evaluation, + counts, + acceptance, + transform, + auxiliary, + ) + return ( + updated, + prepared, + key, + history, + half_history, + chains, + metrics, + ) + + def skip(_: None) -> tuple[Any, ...]: + return ( + state, + context, + random_state, + zeros, + halves, + chain, + self._prepare_block_metrics( + state.particles, state, context, mutation_state + ), + ) + + result = ( + skip(None) + if max_steps == 0 + else cond( + n_steps > 0, + execute, + skip, + None, + xp=xp, + ) + ) + state, context, key, history, half_history, chain, metrics = result + return ( + state, + context, + key, + { + "acceptance_by_step": history, + "acceptance_by_half": half_history, + "steps": n_steps, + "chain": chain, + "metrics": None, + }, + metrics, + ) diff --git a/src/sequince/steps/mutation/repeated.py b/src/sequince/steps/mutation/repeated.py index e3fce915..771ea84d 100644 --- a/src/sequince/steps/mutation/repeated.py +++ b/src/sequince/steps/mutation/repeated.py @@ -3,11 +3,12 @@ from __future__ import annotations from collections.abc import Mapping -from dataclasses import dataclass, replace +from dataclasses import dataclass from typing import TYPE_CHECKING, Any +from ...array_api import namespace from ...utils.pytrees import pytree_dataclass -from ..base import SMCStep, validate_n_steps +from ..base import DynamicBudgetMutation, SMCStep, validate_n_steps from ..context import StepContext from .base import MutationStep from .metrics import ( @@ -15,9 +16,12 @@ MutationMetricsOutput, MutationStepState, ) +from .metrics.base import with_metrics if TYPE_CHECKING: + from ...smc import SMCConfig from ...state import ParticleState + from ...typing import Array @pytree_dataclass( @@ -101,10 +105,7 @@ def apply_with_n_steps(self, state, context, rng, *, n_steps: int): return ( state, context, - replace( - output, - metrics=self.metrics.result(mutation_state, context), - ), + with_metrics(output, self.metrics.result(mutation_state, context)), ) def apply_with_mutation_state( @@ -156,7 +157,150 @@ def apply_with_mutation_state( mutation_state, ) - def initialize_functional_state_and_context(self, state, context): + def _validate_after_round(self) -> None: + """Require an explicit functional implementation for post-round work.""" + if ( + self.after_round is not None + and type(self.after_round).apply_functional + is SMCStep.apply_functional + ): + raise NotImplementedError( + "after_round must explicitly implement apply_functional()." + ) + + def validate_functional_configuration( + self, + config: SMCConfig, + state: ParticleState, + *, + max_steps: int | None = None, + ) -> None: + """Validate each child once with its effective per-round capacity.""" + capacity = ( + self.n_steps if max_steps is None else validate_n_steps(max_steps) + ) + if isinstance(self.mutation, DynamicBudgetMutation): + self.mutation.validate_functional_configuration( + config, + state, + max_steps=(capacity + self.n_rounds - 1) // self.n_rounds, + ) + self._validate_after_round() + elif max_steps is not None: + raise NotImplementedError( + "Repeated mutation child must support DynamicBudgetMutation." + ) + else: + self.mutation.validate_functional_configuration(config, state) + if self.after_round is not None: + self.after_round.validate_functional_configuration(config, state) + + def initialize_functional_metadata( + self, state: ParticleState, metadata: Mapping[str, Any] + ) -> Mapping[str, Any]: + metadata = self.mutation.initialize_functional_metadata( + state, metadata + ) + if self.after_round is not None: + metadata = self.after_round.initialize_functional_metadata( + state, metadata + ) + return metadata + + def apply_functional( + self, state: ParticleState, context: StepContext, random_state: Any + ) -> tuple[ParticleState, StepContext, Any, Any]: + if not isinstance(self.mutation, DynamicBudgetMutation): + # Preserve the existing static functional path for other backends. + return super().apply_functional(state, context, random_state) + state, context, random_state, output, metrics = ( + self.apply_dynamic_budget( + state, + context, + random_state, + n_steps=namespace(state.particles).asarray( + self.n_steps, dtype="int32" + ), + max_steps=self.n_steps, + ) + ) + return ( + state, + context, + random_state, + with_metrics(output, self.metrics.result(metrics, context)), + ) + + def apply_dynamic_budget( + self, + state: ParticleState, + context: StepContext, + random_state: Any, + *, + n_steps: Array, + max_steps: int, + mutation_state: MutationStepState | None = None, + ) -> tuple[ + ParticleState, + StepContext, + Any, + RepeatedMutationStepOutput, + MutationStepState, + ]: + """Split a runtime total by quotient/remainder and share metric state. + + Round capacities use the same split of max_steps, so their sum is + exactly max_steps. Each round exposes its own executed count. + Post-round steps run even for zero-budget rounds. + """ + validate_n_steps(max_steps) + if n_steps.shape != () or not namespace(n_steps).isdtype( + n_steps.dtype, "integral" + ): + raise TypeError("n_steps must be a scalar integer array.") + if not isinstance(self.mutation, DynamicBudgetMutation): + raise NotImplementedError( + "Child must support DynamicBudgetMutation." + ) + self._validate_after_round() + quotient, remainder = n_steps // self.n_rounds, n_steps % self.n_rounds + max_quotient, max_remainder = divmod(max_steps, self.n_rounds) + outputs, after_outputs = [], [] + for index in range(self.n_rounds): + state, context, random_state, output, mutation_state = ( + self.mutation.apply_dynamic_budget( + state, + context, + random_state, + n_steps=quotient + + (index < remainder).astype(n_steps.dtype), + max_steps=max_quotient + (index < max_remainder), + mutation_state=mutation_state, + ) + ) + outputs.append(output) + after_output = None + if self.after_round is not None: + state, context, random_state, after_output = ( + self.after_round.apply_functional( + state, context, random_state + ) + ) + after_outputs.append(after_output) + assert mutation_state is not None # At least one round always runs. + return ( + state, + context, + random_state, + RepeatedMutationStepOutput( + tuple(outputs), tuple(after_outputs), None + ), + mutation_state, + ) + + def initialize_functional_state_and_context( + self, state: ParticleState, context: StepContext + ) -> tuple[ParticleState, StepContext]: state, context = self.mutation.initialize_functional_state_and_context( state, context ) diff --git a/tests/test_functional_nssmc.py b/tests/test_functional_nssmc.py index 89b3f86c..eb1dc667 100644 --- a/tests/test_functional_nssmc.py +++ b/tests/test_functional_nssmc.py @@ -368,10 +368,6 @@ def broken(values: Any, state: Any, context: Any) -> float: ({"logging_frequency": 1}, "logging_frequency=0"), ({"mutation": "emcee"}, "EmceeMutation"), ({"mutation": "eryn"}, "ErynMutation"), - ( - {"mutation": "differential-evolution"}, - "DifferentialEvolutionMutation", - ), ], ) def test_unsupported_configurations( @@ -649,3 +645,25 @@ def test_mixed_precision_bookkeeping_and_thresholds( np.testing.assert_array_equal( jax.random.key_data(key), jax.random.key_data(expected_key) ) + + +@pytest.mark.parametrize("mode", ["functional", "compiled"]) +def test_differential_evolution_matches_eager(mode: str) -> None: + state = ParticleState(jnp.arange(8.0)[:, None]) + # Dyadic proposals keep this integration comparison exact in float32; + # mixtures and noisy proposals are covered by the DE kernel tests. + options = dict( + mutation="differential-evolution", + mutation_n_steps=2, + mutation_kwargs={ + "gamma": 0.5, + "gamma_one_probability": 0, + "noise_scale": 0, + }, + ) + expected, expected_key = run_mode("eager", state, **options) + actual, key = run_mode(mode, state, **options) + assert_results(actual, expected) + np.testing.assert_array_equal( + jax.random.key_data(key), jax.random.key_data(expected_key) + ) diff --git a/tests/test_mutation/test_acceptance_policy.py b/tests/test_mutation/test_acceptance_policy.py index 7f71cccd..1ce2050b 100644 --- a/tests/test_mutation/test_acceptance_policy.py +++ b/tests/test_mutation/test_acceptance_policy.py @@ -142,3 +142,27 @@ def test_policy_bounds_initial_and_unmeasured_budget( def test_invalid_move_bounds(minimum, maximum, error): with pytest.raises(error): AcceptanceRatePolicy(3, min_steps=minimum, max_steps=maximum) + + +@pytest.mark.parametrize("shape", [(), (1,), (1, 1)]) +def test_eager_normalizes_single_count_without_mutating_metrics( + shape: tuple[int, ...], context_factory +) -> None: + attempted = np.full(shape, 10.0) + accepted = np.full(shape, 2.5) + metrics = MutationMetricsOutput( + 4, attempted, accepted, values={"other": 7} + ) + policy = AcceptanceRatePolicy(2, min_steps=0, max_steps=20) + + assert ( + policy.update( + current_steps=4, metrics=metrics, context=context_factory() + ) + == 8 + ) + assert metrics.n_attempted is attempted + assert metrics.n_accepted is accepted + np.testing.assert_array_equal(attempted, np.full(shape, 10.0)) + np.testing.assert_array_equal(accepted, np.full(shape, 2.5)) + assert metrics.values == {"other": 7} diff --git a/tests/test_mutation/test_dynamic_de.py b/tests/test_mutation/test_dynamic_de.py new file mode 100644 index 00000000..f41cde7e --- /dev/null +++ b/tests/test_mutation/test_dynamic_de.py @@ -0,0 +1,491 @@ +"""Runtime budgets preserve the eager DE kernel and complete-block semantics.""" + +from dataclasses import replace +from typing import Any + +import numpy as np +import pytest +from orng import RandomGenerator + +from sequince.state import ParticleState +from sequince.steps import ( + AdaptMutationSteps, + DifferentialEvolutionMutation, + ESJDMetric, + RelativeJumpDistanceMetric, + RepeatedMutationStep, + StepContext, +) +from sequince.steps.base import SMCStep +from sequince.steps.mutation.adaptive.policies.acceptance import ( + AcceptanceRatePolicy, +) +from sequince.steps.mutation.metrics.de import DEScaleMetrics +from sequince.target import Target, TargetEvaluation +from sequince.transforms import AffineTransform + +jax = pytest.importorskip("jax") +jnp = pytest.importorskip("jax.numpy") + + +def gaussian(x: Any, context: StepContext) -> Any: + return -jnp.sum(x * x, axis=1) / 2 + + +class CachedGaussian(Target): + def evaluate(self, particles, context, **kwargs): + return TargetEvaluation({"log_prob": gaussian(particles, context)}) + + def log_prob(self, particles, context, *, evaluation=None): + return evaluation["log_prob"] + + +def initialize(step: Any, state: ParticleState) -> tuple[Any, Any]: + from sequince.smc import SMCConfig + + step.validate_functional_configuration( + SMCConfig( + steps=(step,), + callbacks=(), + checkpoint_writers=(), + auto_normalize=True, + ), + state, + ) + context = StepContext( + t=jnp.asarray(0, dtype=jnp.int32), + metadata=step.initialize_functional_metadata(state, {}), + ) + state, context = step.initialize_functional_state_and_context( + state, context + ) + # Convert scalar counters too so scan signatures match the first call. + return jax.tree.map(jnp.asarray, (state, context)) + + +def assert_tree_close(left: Any, right: Any) -> None: + assert jax.tree.structure(left) == jax.tree.structure(right) + for a, b in zip( + jax.tree.leaves(left), jax.tree.leaves(right), strict=True + ): + np.testing.assert_allclose(a, b, rtol=2e-5, atol=2e-5) + + +@pytest.mark.parametrize("store", [False, True]) +@pytest.mark.parametrize("transformed,cached", [(False, False), (True, True)]) +def test_dynamic_matches_eager_and_reuses_compilation( + store, transformed, cached +) -> None: + step = DifferentialEvolutionMutation( + CachedGaussian() if cached else gaussian, + transform=AffineTransform() if transformed else None, + store_chains=store, + scale_multipliers=(0.3, 1.0), + gamma_randomization="bilby", + metrics=[ + DEScaleMetrics((0.3, 1.0)), + ESJDMetric(), + RelativeJumpDistanceMetric(reference_radius=1.0), + ], + ) + state, context = initialize( + step, + ParticleState( + jnp.asarray(np.random.default_rng(8).normal(size=(9, 2))) + ), + ) + traces = [] + + @jax.jit + def run(state, context, key, budget): + traces.append(1) + return step.apply_dynamic_budget( + state, context, key, n_steps=budget, max_steps=5 + ) + + key = jax.random.key(9) + for budget in (0, 1, 3, 5, 0): + rng = RandomGenerator.from_xp(jnp, generator=key) + eager_state, eager_context, eager, eager_metrics = ( + step.apply_with_mutation_state(state, context, rng, n_steps=budget) + ) + updated, actual_context, actual_key, output, metrics = run( + state, context, key, jnp.asarray(budget, dtype=jnp.int32) + ) + assert_tree_close(updated, eager_state) + assert_tree_close( + actual_context.evaluation_counts, eager_context.evaluation_counts + ) + np.testing.assert_array_equal( + jax.random.key_data(actual_key), jax.random.key_data(rng.state()) + ) + assert_tree_close( + step.metrics.result(metrics, actual_context), + step.metrics.result(eager_metrics, eager_context), + ) + assert int(output["steps"]) == budget + for name in ("acceptance_by_step", "acceptance_by_half"): + if budget: + np.testing.assert_allclose( + output[name][:budget], np.asarray(eager[name]) + ) + np.testing.assert_array_equal(output[name][budget:], 0) + if store: + assert output["chain"].shape == (5, 9, 2) + np.testing.assert_allclose( + output["chain"][:budget], eager["chain"], rtol=2e-5, atol=2e-5 + ) + np.testing.assert_array_equal(output["chain"][budget:], 0) + else: + assert output["chain"] is None + if budget == 0: + assert_tree_close(actual_context, context) + np.testing.assert_array_equal( + jax.random.key_data(actual_key), jax.random.key_data(key) + ) + # Feed results straight back into the same executable: no warm-up call + # may change a context/cache leaf's shape, dtype or weak scalar type. + state, context, key = updated, actual_context, actual_key + assert len(traces) == 1 + + +class Negate(SMCStep): + def apply(self, state, context, rng): + return ( + state.replace_particles(-state.particles), + replace( + context, + next_observation_index=context.next_observation_index + 1, + ), + None, + ) + + def apply_functional(self, state, context, key): + state, context, output = self.apply(state, context, None) + return state, context, key, output + + +@pytest.mark.parametrize("budget", [0, 1, 2, 5, 7]) +@pytest.mark.parametrize("transformed", [False, True]) +def test_repeated_matches_eager_with_zero_rounds(budget, transformed) -> None: + child = DifferentialEvolutionMutation( + gaussian, + transform=AffineTransform() if transformed else None, + metrics=[ + ESJDMetric(), + RelativeJumpDistanceMetric(reference_radius=1.0), + ], + ) + step = RepeatedMutationStep(child, n_rounds=3, after_round=Negate()) + state, context = initialize( + step, ParticleState(jax.random.normal(jax.random.key(6), (9, 2))) + ) + capacity = 2 if budget <= 2 else 7 + key = jax.random.key(8) + rng = RandomGenerator.from_xp(jnp, generator=key) + expected, expected_context, expected_output = step.apply_with_n_steps( + state, context, rng, n_steps=budget + ) + actual, actual_context, actual_key, output, metrics = jax.jit( + lambda s, c, k, n: step.apply_dynamic_budget( + s, c, k, n_steps=n, max_steps=capacity + ) + )(state, context, key, jnp.asarray(budget, dtype=jnp.int32)) + assert_tree_close(actual, expected) + assert_tree_close(actual_context, expected_context) + assert_tree_close( + step.metrics.result(metrics, actual_context), expected_output.metrics + ) + np.testing.assert_array_equal( + jax.random.key_data(actual_key), jax.random.key_data(rng.state()) + ) + assert [int(o["steps"]) for o in output.round_outputs] == [ + budget // 3 + (i < budget % 3) for i in range(3) + ] + assert all(o["metrics"] is None for o in output.round_outputs) + assert int(actual_context.next_observation_index) == 3 + assert [ + o["acceptance_by_step"].shape[0] for o in output.round_outputs + ] == [capacity // 3 + (i < capacity % 3) for i in range(3)] + + +@pytest.mark.parametrize("initial_steps", [0, 1]) +def test_adaptation_scan_executes_de(initial_steps: int) -> None: + child = RepeatedMutationStep( + DifferentialEvolutionMutation(gaussian), n_rounds=2 + ) + step = AdaptMutationSteps( + child, + AcceptanceRatePolicy(3, min_steps=0, max_steps=6), + initial_steps=initial_steps, + min_steps=0, + max_steps=6, + ) + state, context = initialize( + step, ParticleState(jax.random.normal(jax.random.key(6), (21, 2))) + ) + + def body(carry, iteration): + state, context, key = carry + context = replace(context, t=iteration) + state, context, key, output = step.apply_functional( + state, context, key + ) + return (state, context, key), output.metrics.n_steps + + carry = (state, context, jax.random.key(9)) + actual, budgets = jax.jit( + lambda c: jax.lax.scan(body, c, jnp.arange(5, dtype=jnp.int32)) + )(carry) + assert int(budgets[0]) == initial_steps + assert np.any(np.asarray(budgets[1:]) != initial_steps) + expected = carry + for i in range(5): + expected, _ = body(expected, jnp.asarray(i, dtype=jnp.int32)) + assert_tree_close(actual[:2], expected[:2]) + np.testing.assert_array_equal( + jax.random.key_data(actual[2]), jax.random.key_data(expected[2]) + ) + + +@pytest.mark.parametrize("capacity", [0, 8]) +def test_skipped_target_and_rng(capacity) -> None: + calls = [] + + def target(x, context): + jax.debug.callback(lambda _: calls.append(1), x[0, 0], ordered=True) + return gaussian(x, context) + + step = DifferentialEvolutionMutation(target) + state, context = initialize(step, ParticleState(jnp.ones((5, 2)))) + key = jax.random.key(2) + result = jax.jit( + lambda n: step.apply_dynamic_budget( + state, context, key, n_steps=n, max_steps=capacity + ) + )(jnp.asarray(0, dtype=jnp.int32)) + jax.block_until_ready(result) + jax.effects_barrier() + assert calls == [] + assert_tree_close(result[0], state) + np.testing.assert_array_equal( + jax.random.key_data(result[2]), jax.random.key_data(key) + ) + assert result[3]["acceptance_by_step"].shape == (capacity,) + + +def test_gaussian_stationarity() -> None: + # Start at stationarity: 5000 particles allow mean SE ~0.014 and variance + # SE ~0.020. Tolerances 0.07/0.10 allow five marginal SE plus weak ensemble + # dependence. An incorrect target or acceptance rule changes these moments. + state = ParticleState(jax.random.normal(jax.random.key(10), (5000, 2))) + step = DifferentialEvolutionMutation( + gaussian, scale_multipliers=(0.3, 1.0) + ) + state, context = initialize(step, state) + result = jax.jit( + lambda s, c, k: step.apply_dynamic_budget( + s, c, k, n_steps=jnp.asarray(20, dtype=jnp.int32), max_steps=25 + ) + )(state, context, jax.random.key(11)) + np.testing.assert_allclose( + jnp.mean(result[0].particles, axis=0), 0, atol=0.07 + ) + np.testing.assert_allclose( + jnp.cov(result[0].particles.T), np.eye(2), atol=0.10 + ) + + +def test_nested_rounds_and_continuing_state() -> None: + child = DifferentialEvolutionMutation(gaussian, metrics=[ESJDMetric()]) + step = RepeatedMutationStep( + RepeatedMutationStep(child, n_rounds=2), n_rounds=2 + ) + state, context = initialize( + step, ParticleState(jnp.arange(18.0).reshape(9, 2) / 8) + ) + key = jax.random.key(8) + rng = RandomGenerator.from_xp(jnp, generator=key) + expected, expected_context, expected_output = step.apply_with_n_steps( + state, context, rng, n_steps=3 + ) + result = jax.jit( + lambda s, c, k: step.apply_dynamic_budget( + s, c, k, n_steps=jnp.array(3, dtype=jnp.int32), max_steps=5 + ) + )(state, context, key) + assert_tree_close(result[0], expected) + assert_tree_close( + step.metrics.result(result[4], result[1]), expected_output.metrics + ) + assert_tree_close(result[1], expected_context) + np.testing.assert_array_equal( + jax.random.key_data(result[2]), jax.random.key_data(rng.state()) + ) + + +def test_validation_and_initialization_forwarding() -> None: + from sequince.steps.mutation import ( + GaussianRandomWalk, + MetropolisHastingsMutation, + ) + + state = ParticleState(jnp.ones((5, 2))) + unsupported = AdaptMutationSteps( + MetropolisHastingsMutation(gaussian, GaussianRandomWalk()), + initial_steps=1, + min_steps=0, + max_steps=5, + ) + with pytest.raises(NotImplementedError, match="DynamicBudgetMutation"): + unsupported.initialize_functional_state_and_context( + state, StepContext(t=0) + ) + + class EagerPost(SMCStep): + pass + + unsupported = AdaptMutationSteps( + RepeatedMutationStep( + DifferentialEvolutionMutation(gaussian), after_round=EagerPost() + ), + initial_steps=1, + min_steps=0, + max_steps=5, + ) + with pytest.raises(NotImplementedError, match="after_round"): + initialize(unsupported, state) + with pytest.raises(ValueError, match="four particles"): + initialize( + DifferentialEvolutionMutation(gaussian), + ParticleState(jnp.ones((3, 2))), + ) + with pytest.raises(NotImplementedError, match="Callable transform_refit"): + initialize( + DifferentialEvolutionMutation( + gaussian, + transform=AffineTransform(), + transform_refit=lambda p, c: True, + ), + state, + ) + + +def test_no_optional_metrics_and_no_padding_work() -> None: + calls = [] + + def target(x, context): + jax.debug.callback(lambda _: calls.append(1), x[0, 0], ordered=True) + return gaussian(x, context) + + step = DifferentialEvolutionMutation( + target, noise_scale=0.0, gamma_one_probability=1.0 + ) + state, context = initialize( + step, ParticleState(jnp.arange(18.0).reshape(9, 2) / 8) + ) + key = jax.random.key(8) + result = jax.jit( + lambda s, c, k: step.apply_dynamic_budget( + s, c, k, n_steps=jnp.array(2, dtype=jnp.int32), max_steps=8 + ) + )(state, context, key) + jax.block_until_ready(result) + jax.effects_barrier() + assert ( + len(calls) == 5 + ) # Initial population, then two half-targets per sweep. + assert int(result[1].evaluation_counts.log_target_evaluations) == 27 + assert result[4].states == () + assert int(result[4].n_attempted) == 18 + assert result[3]["chain"] is None + np.testing.assert_array_equal(result[3]["acceptance_by_step"][2:], 0) + + +def test_compiled_adapter_pipeline_signature() -> None: + from sequince import SequentialMonteCarlo + from sequince.jax import compile_functional_iteration + + step = AdaptMutationSteps( + DifferentialEvolutionMutation( + CachedGaussian(), transform=AffineTransform() + ), + AcceptanceRatePolicy(3, min_steps=0, max_steps=6), + initial_steps=1, + min_steps=0, + max_steps=6, + ) + sampler = SequentialMonteCarlo([step]) + state = ParticleState(jax.random.normal(jax.random.key(6), (21, 2))) + key = jax.random.key(9) + compiled = compile_functional_iteration(sampler, state, key) + result, _ = sampler.run_functional( + state, random_state=key, iteration=compiled, num_steps=4 + ) + assert len(result) == 4 + carry = result.context.metadata[step.metadata_key] + assert int(carry.current_iteration) == 3 + assert int(carry.last_updated_iteration) == 3 + assert int(carry.current_n_steps) > 1 + + +def test_validation_uses_effective_capacity_once() -> None: + capacities: list[int] = [] + + class RecordingDE(DifferentialEvolutionMutation): + def _validate_dynamic_budget( + self, state: ParticleState, *, max_steps: int + ) -> None: + capacities.append(max_steps) + super()._validate_dynamic_budget(state, max_steps=max_steps) + + step = AdaptMutationSteps( + RepeatedMutationStep(RecordingDE(gaussian, n_steps=99), n_rounds=3), + initial_steps=1, + min_steps=0, + max_steps=7, + ) + initialize(step, ParticleState(jnp.ones((5, 2)))) + assert capacities == [3] + + +@pytest.mark.parametrize("repeated", [False, True]) +@pytest.mark.parametrize("budget", [jnp.array([1]), jnp.array(1.0)]) +def test_direct_dynamic_budget_rejects_invalid_arguments( + repeated: bool, budget: Any +) -> None: + child = DifferentialEvolutionMutation(gaussian) + step = RepeatedMutationStep(child) if repeated else child + state, context = initialize(step, ParticleState(jnp.ones((5, 2)))) + key = jax.random.key(0) + with pytest.raises(TypeError, match="scalar integer"): + step.apply_dynamic_budget( + state, context, key, n_steps=budget, max_steps=2 + ) + with pytest.raises(ValueError, match="n_steps"): + step.apply_dynamic_budget( + state, context, key, n_steps=jnp.array(1), max_steps=-1 + ) + + +def test_repeated_rejects_eager_child_for_dynamic_budget() -> None: + from sequince.steps.mutation import ( + GaussianRandomWalk, + MetropolisHastingsMutation, + ) + + child = RepeatedMutationStep( + MetropolisHastingsMutation(gaussian, GaussianRandomWalk()) + ) + step = AdaptMutationSteps(child, initial_steps=1, min_steps=0, max_steps=5) + state = ParticleState(jnp.ones((5, 2))) + with pytest.raises(NotImplementedError, match="DynamicBudgetMutation"): + initialize(step, state) + with pytest.raises(NotImplementedError, match="DynamicBudgetMutation"): + child.apply_dynamic_budget( + state, + StepContext(t=0), + jax.random.key(0), + n_steps=jnp.array(1), + max_steps=5, + ) diff --git a/tests/test_mutation/test_functional_budget.py b/tests/test_mutation/test_functional_budget.py new file mode 100644 index 00000000..5180fb84 --- /dev/null +++ b/tests/test_mutation/test_functional_budget.py @@ -0,0 +1,558 @@ +"""Pure budget transitions, independent of mutation execution.""" + +from dataclasses import fields, replace +from pathlib import Path +from typing import Any + +import numpy as np +import pytest + +from sequince.array_api import asarray, to_numpy +from sequince.checkpoint import SMCCheckpoint +from sequince.state import ParticleState +from sequince.steps import AdaptMutationSteps, MutationBudgetState, StepContext +from sequince.steps.mutation.adaptive.policies.acceptance import ( + AcceptanceRatePolicy, +) +from sequince.steps.mutation.adaptive.policies.fixed import ( + FixedMutationStepPolicy, +) +from sequince.steps.mutation.metrics import MutationMetricsOutput +from sequince.typing import Array + + +class UnusedMutation: + def apply_with_n_steps(self, *args: Any, **kwargs: Any) -> Any: + raise AssertionError("Budget operations must not execute mutation.") + + +def adapter(policy: Any = None, **kwargs: Any) -> AdaptMutationSteps: + return AdaptMutationSteps( + UnusedMutation(), + policy, + initial_steps=4, + min_steps=0, + max_steps=20, + **kwargs, + ) + + +def initialize(step: AdaptMutationSteps, state: ParticleState) -> StepContext: + return StepContext( + t=0, metadata=step.initialize_functional_metadata(state, {}) + ) + + +@pytest.mark.parametrize( + "target,minimum,maximum,safeguard,attempted,accepted,current,expected", + [ + (1.5, 0, 20, 1e-6, 10, 2.5, 4, 6), + (2.0, 0, 20, 0.25, 10, 0, 4, 8), + (2.0, 0, 20, 1e-6, 10, 0, 4, 20), + (2.0, 0, 20, 1e-6, 0, 0, 0, 1), + (2.0, 0, 20, 1e-6, 0, 0, 7, 7), + (2.0, 5, 20, 1e-6, 10, 10, 7, 5), + (1e300, 0, 20, 1e-6, 10, 10, 4, 20), + (1e300, 0, 20, 1e-300, 10, 0, 4, 20), + (1e-300, 0, 20, 1e-6, 10, 10, 4, 1), + (1e-300, 0, 20, 1e-300, 10, 0, 4, 1), + (2.0, 0, 0, 1e-6, 10, 0, 0, 0), + (2.0, 0, 2**24, 1e-300, 10, 0, 4, 2**24), + ], +) +def test_policy_agreement( + backend, + backend_factory, + target, + minimum, + maximum, + safeguard, + attempted, + accepted, + current, + expected, +) -> None: + case = backend_factory(backend) + policy = AcceptanceRatePolicy( + target, + min_steps=minimum, + max_steps=maximum, + min_acceptance=safeguard, + ) + policy.validate_functional_configuration() + budget = asarray(current, like=case.log_weights, dtype="int32") + metrics = MutationMetricsOutput( + budget, + asarray(attempted, like=case.log_weights), + asarray(accepted, like=case.log_weights), + ) + context = StepContext(t=0) + initial = policy.initialise_functional( + initial_steps=budget, context=context + ) + assert int(to_numpy(initial)) == policy.initialise( + initial_steps=current, context=context + ) + result = policy.update_functional( + current_steps=budget, metrics=metrics, context=context + ) + if backend == "jax": + import jax + + compiled = jax.jit( + lambda steps, output: policy.update_functional( + current_steps=steps, metrics=output, context=context + ) + )(budget, metrics) + assert int(to_numpy(compiled)) == expected + assert result.dtype == budget.dtype + assert result.shape == () + assert case.matches_namespace(result) + assert ( + int(to_numpy(result)) + == expected + == policy.update( + current_steps=current, metrics=metrics, context=context + ) + ) + + +@pytest.mark.parametrize("policy", [FixedMutationStepPolicy(), None]) +def test_fixed_decisions_and_initialization( + policy, backend, backend_factory +) -> None: + case = backend_factory(backend) + step = adapter(policy) + context = initialize(step, case.state()) + prepared, budget = step.prepare_budget_functional(context) + assert int(to_numpy(budget)) == 4 + updated = step.update_budget_functional( + MutationMetricsOutput(budget, budget * 0, budget * 0), prepared + ) + promoted, budget = step.prepare_budget_functional(replace(updated, t=1)) + assert int(to_numpy(budget)) == 4 + carry = promoted.metadata[step.metadata_key] + for field in fields(carry): + leaf = getattr(carry, field.name) + assert leaf.shape == () + assert leaf.dtype == case.xp.int32 + + +def test_functional_runs_leave_shared_adapter_unchanged( + particle_state, +) -> None: + step = adapter(AcceptanceRatePolicy(2, min_steps=0, max_steps=20)) + attributes = step.__dict__.copy() + policy_attributes = step.policy.__dict__.copy() + initial = initialize(step, particle_state) + prepared, budget = step.prepare_budget_functional(initial) + updated = step.update_budget_functional( + MutationMetricsOutput(budget, np.array(10), np.array(2.5)), prepared + ) + independent = initialize(step, particle_state) + assert int(updated.metadata[step.metadata_key].next_n_steps) == 8 + assert int(independent.metadata[step.metadata_key].next_n_steps) == 4 + assert int(initial.metadata[step.metadata_key].current_iteration) == -1 + assert step.__dict__ == attributes + assert step.policy.__dict__ == policy_attributes + + +@pytest.mark.parametrize("format", ["pickle", "hdf5"]) +def test_resume_and_multiple_adapters(particle_state, tmp_path: Path, format): + one = adapter( + AcceptanceRatePolicy(2, min_steps=0, max_steps=20), metadata_key="one" + ) + two = adapter(metadata_key="two") + metadata = one.initialize_functional_metadata( + particle_state, {"other": 12} + ) + metadata = two.initialize_functional_metadata(particle_state, metadata) + context, budget = one.prepare_budget_functional( + StepContext(t=0, metadata=metadata) + ) + context = one.update_budget_functional( + MutationMetricsOutput(budget, np.array(10), np.array(2.5)), context + ) + context, _ = two.prepare_budget_functional(context) + checkpoint = SMCCheckpoint( + states=(particle_state,), + next_iteration=1, + next_observation_index=0, + metadata=context.metadata, + outputs=(), + step_states=(), + ) + path = tmp_path / f"checkpoint.{format}" + if format == "hdf5": + h5py = pytest.importorskip("h5py") + with h5py.File(path, "w") as handle: + checkpoint.save_hdf5(handle) + with h5py.File(path, "r") as handle: + restored = SMCCheckpoint.load_hdf5(handle) + else: + checkpoint.save_pickle(path) + restored = SMCCheckpoint.load_pickle(path) + reconstructed = adapter( + AcceptanceRatePolicy(2, min_steps=0, max_steps=20), metadata_key="one" + ) + metadata = reconstructed.initialize_functional_metadata( + particle_state, restored.metadata + ) + assert metadata is restored.metadata + replayed, budget = reconstructed.prepare_budget_functional( + StepContext(t=0, metadata=metadata) + ) + assert int(budget) == 4 + replayed = reconstructed.update_budget_functional( + MutationMetricsOutput(budget, np.array(10), np.array(0)), replayed + ) + promoted, budget = reconstructed.prepare_budget_functional( + replace(replayed, t=1) + ) + assert int(budget) == 8 + assert int(promoted.metadata["two"].current_n_steps) == 4 + assert promoted.metadata["other"] == 12 + + +def test_custom_functional_opt_in_and_eager_only(particle_state) -> None: + class Custom(FixedMutationStepPolicy): + def initialise_functional(self, *, initial_steps, context): + return initial_steps + 1 + + def update_functional(self, *, current_steps, metrics, context): + return current_steps + 100 + + step = adapter(Custom()) + context, budget = step.prepare_budget_functional( + initialize(step, particle_state) + ) + assert int(budget) == 5 + context = step.update_budget_functional( + MutationMetricsOutput(5, 10, 5), context + ) + assert int(context.metadata[step.metadata_key].next_n_steps) == 20 + + class EagerOnly: + def initialise(self, *, initial_steps, context): + return initial_steps + + def update(self, *, current_steps, metrics, context): + return current_steps + + eager = adapter(EagerOnly()) + assert eager._freeze_budget(StepContext(t=0)) == 4 + with pytest.raises( + NotImplementedError, match="FunctionalMutationStepPolicy" + ): + initialize(eager, particle_state) + with pytest.raises(NotImplementedError, match="eager execution only"): + step.apply_functional(particle_state, context, None) + + +def test_invalid_static_configuration_and_missing_carry( + particle_state, +) -> None: + with pytest.raises(ValueError, match="metadata_key"): + adapter(metadata_key="") + with pytest.raises(TypeError, match="Initialize functional"): + adapter().prepare_budget_functional(StepContext(t=0)) + with pytest.raises(TypeError, match="MutationBudgetState"): + adapter().initialize_functional_metadata( + particle_state, {"mutation_budget": 3} + ) + large = AdaptMutationSteps( + UnusedMutation(), initial_steps=1, min_steps=0, max_steps=2**24 + 1 + ) + with pytest.raises(ValueError, match="max_steps"): + initialize(large, particle_state) + with pytest.raises(ValueError, match="max_steps"): + AcceptanceRatePolicy(2, min_steps=0, max_steps=2**24 + 1) + for carry in ( + MutationBudgetState(*(np.array(0, dtype=np.int64) for _ in range(4))), + MutationBudgetState[int].initial(4, -1), + ): + with pytest.raises(TypeError, match="scalar int32"): + adapter().initialize_functional_metadata( + particle_state, {"mutation_budget": carry} + ) + + +@pytest.mark.parametrize("accepted", [0.0, 1.0]) +def test_shared_ceiling_rounding(accepted: float) -> None: + policy = AcceptanceRatePolicy( + 1.1, min_steps=0, max_steps=20, min_acceptance=0.1 + ) + budget = np.array(4, dtype=np.int32) + metrics = MutationMetricsOutput(budget, np.array(10.0), np.array(accepted)) + context = StepContext(t=0) + # Both paths divide before the ceiling, using the same stored binary floats. + assert ( + policy.update(current_steps=4, metrics=metrics, context=context) == 11 + ) + assert ( + policy.update_functional( + current_steps=budget, metrics=metrics, context=context + ) + == 11 + ) + + +def test_scalar_metrics_required_and_inputs_preserved() -> None: + policy = AcceptanceRatePolicy(2, min_steps=0, max_steps=20) + budget = np.array(4, dtype=np.int32) + attempted, accepted = np.array(10.0), np.array(2.5) + metrics = MutationMetricsOutput(budget, attempted, accepted) + policy.update_functional( + current_steps=budget, metrics=metrics, context=StepContext(t=0) + ) + assert budget == 4 + assert attempted == 10 + assert accepted == 2.5 + with pytest.raises(TypeError, match="scalar"): + policy.update_functional( + current_steps=budget, + metrics=MutationMetricsOutput(budget, np.ones(2), accepted), + context=StepContext(t=0), + ) + + +def test_optree_carry_roundtrip(particle_state) -> None: + import optree + + context = initialize(adapter(), particle_state) + carry = context.metadata["mutation_budget"] + leaves, structure = optree.tree_flatten(carry, namespace="sequince") + assert len(leaves) == 4 + restored = optree.tree_unflatten(structure, leaves) + assert isinstance(restored, MutationBudgetState) + assert int(restored.current_iteration) == -1 + assert int(restored.next_n_steps) == 4 + + +class LifecyclePolicy(FixedMutationStepPolicy): + """Exercise initial decisions and clipping independently of acceptance.""" + + def initialise( + self, *, initial_steps: int | Array, context: StepContext + ) -> int | Array: + return initial_steps + 2 + + def update( + self, + *, + current_steps: int | Array, + metrics: MutationMetricsOutput, + context: StepContext, + ) -> int | Array: + return metrics.values["proposal"] + + initialise_functional = initialise + update_functional = update + + +@pytest.mark.parametrize("resume_after", [0, 1, 4, 7, 9]) +def test_eager_and_functional_lifecycle( + backend, backend_factory, resume_after: int +) -> None: + import pickle + + case = backend_factory(backend) + eager, functional = adapter(LifecyclePolicy()), adapter(LifecyclePolicy()) + context = initialize(functional, case.state()) + assert eager.current_n_steps == eager.next_n_steps == 4 + carry = context.metadata[functional.metadata_key] + assert int(to_numpy(carry.current_iteration)) == -1 + assert int(to_numpy(carry.last_updated_iteration)) == -1 + assert int(to_numpy(carry.current_n_steps)) == 4 + assert int(to_numpy(carry.next_n_steps)) == 4 + + prepare = functional.prepare_budget_functional + update = functional.update_budget_functional + if backend == "jax": + import jax + + prepare, update = jax.jit(prepare), jax.jit(update) + + operations = [ + ("prepare", 3, None, 6, 6), + ("prepare", 3, None, 6, 6), + # Advancing without completed metrics retains the frozen budget. + ("prepare", 4, None, 6, 6), + ("update", 4, 99, 6, 20), + ("update", 4, 0, 6, 20), + ("prepare", 4, None, 6, 20), + ("prepare", 5, None, 20, 20), + ("update", 5, -7, 20, 0), + ("update", 5, 8, 20, 0), + ("prepare", 6, None, 0, 0), + ("update", 6, 5, 0, 5), + ("prepare", 7, None, 5, 5), + ] + for index, (operation, iteration, proposal, frozen, pending) in enumerate( + operations + ): + if index == resume_after: + eager_state, metadata = pickle.loads( + pickle.dumps((eager.state_dict(), context.metadata)) + ) + eager, functional = ( + adapter(LifecyclePolicy()), + adapter(LifecyclePolicy()), + ) + eager.load_state_dict(eager_state) + initialized = functional.initialize_functional_metadata( + case.state(), metadata + ) + assert initialized is metadata + context = replace(context, metadata=initialized) + prepare = functional.prepare_budget_functional + update = functional.update_budget_functional + if backend == "jax": + prepare, update = jax.jit(prepare), jax.jit(update) + + eager_context = StepContext(t=iteration) + context = replace( + context, t=asarray(iteration, like=case.log_weights, dtype="int32") + ) + if operation == "prepare": + assert eager._freeze_budget(eager_context) == frozen + context, budget = prepare(context) + assert int(to_numpy(budget)) == frozen + else: + metrics = MutationMetricsOutput( + asarray(frozen, like=case.log_weights, dtype="int32"), + asarray(0, like=case.log_weights, dtype="int32"), + asarray(0, like=case.log_weights, dtype="int32"), + values={ + "proposal": asarray( + proposal, like=case.log_weights, dtype="int32" + ) + }, + ) + # This custom diagnostic supplies intentionally out-of-bound + # budgets while keeping the core mutation counts valid. + eager_metrics = replace(metrics, values={"proposal": proposal}) + eager._adapt( + eager_metrics, + eager_context, + initial_context=eager_context, + n_steps=eager.current_n_steps, + ) + context = update(metrics, context) + carry = context.metadata[functional.metadata_key] + assert ( + eager.current_n_steps + == int(to_numpy(carry.current_n_steps)) + == frozen + ) + assert eager.next_n_steps == pending + assert int(to_numpy(carry.next_n_steps)) == pending + for name, value in eager.state_dict()["budget"].items(): + assert value == int(to_numpy(getattr(carry, name))) + + +def test_shared_lifecycle_preserves_stateful_eager_only_policy() -> None: + class EagerPolicy: + def __init__(self) -> None: + self.initialisations = 0 + self.updates = 0 + + def initialise( + self, *, initial_steps: int, context: StepContext + ) -> int: + self.initialisations += 1 + return initial_steps + + def update( + self, + *, + current_steps: int, + metrics: MutationMetricsOutput, + context: StepContext, + ) -> int: + self.updates += 1 + return current_steps + 7 + + def state_dict(self) -> dict[str, int]: + return dict( + initialisations=self.initialisations, updates=self.updates + ) + + def load_state_dict(self, state: dict[str, int]) -> None: + self.initialisations = state["initialisations"] + self.updates = state["updates"] + + def build() -> AdaptMutationSteps: + return AdaptMutationSteps( + UnusedMutation(), + EagerPolicy(), + initial_steps=2**80, + min_steps=0, + max_steps=2**81, + ) + + step = build() + context = StepContext(t=0) + for _ in range(2): + assert step._freeze_budget(context) == 2**80 + step._adapt( + MutationMetricsOutput(2**80, 0, 0), + context, + initial_context=context, + n_steps=2**80, + ) + saved = step.state_dict() + assert saved["policy"] == {"initialisations": 1, "updates": 1} + assert saved["budget"]["next_n_steps"] == 2**80 + 7 + resumed = build() + resumed.load_state_dict(saved) + assert resumed._freeze_budget(context) == 2**80 + resumed._adapt( + MutationMetricsOutput(2**80, 0, 0), + context, + initial_context=context, + n_steps=2**80, + ) + assert resumed.state_dict()["policy"] == saved["policy"] + assert resumed._freeze_budget(replace(context, t=1)) == 2**80 + 7 + + +@pytest.mark.parametrize( + "changes,error", + [ + ({"current_n_steps": None}, TypeError), + ({"next_n_steps": True}, TypeError), + ({"next_n_steps": 1.5}, TypeError), + ({"next_n_steps": -1}, ValueError), + ({"next_n_steps": 21}, ValueError), + ({"current_iteration": -2}, ValueError), + ({"last_updated_iteration": 0}, ValueError), + ], +) +def test_complete_budget_checkpoint_validation(changes, error) -> None: + step = adapter() + saved = step.state_dict() + saved["budget"].update(changes) + before = step.state_dict() + with pytest.raises(error): + step.load_state_dict(saved) + assert step.state_dict() == before + + +def test_incomplete_and_legacy_checkpoints_rejected() -> None: + step = adapter() + before = step.state_dict() + assert before["budget"] == dict( + current_iteration=-1, + current_n_steps=4, + next_n_steps=4, + last_updated_iteration=-1, + ) + with pytest.raises(ValueError, match="budget"): + step.load_state_dict( + {"mutation": {}, "policy": {}, "policy_initialised": False} + ) + incomplete = step.state_dict() + del incomplete["budget"]["next_n_steps"] + with pytest.raises(ValueError, match="four carry fields"): + step.load_state_dict(incomplete)