add noise feature

Author: SimonBlanke

src/surfaces/noise/__init__.py

@@ -0,0 +1,50 @@
+# Author: Simon Blanke
+# Email: [email protected]
+# License: MIT License
+
+"""Noise layers for adding stochastic disturbances to test functions.
+
+This module provides noise classes that can be passed to test functions
+to simulate noisy evaluations. Useful for testing algorithm robustness
+to measurement uncertainty.
+
+Examples
+--------
+Basic usage with a test function:
+
+>>> from surfaces.test_functions import SphereFunction
+>>> from surfaces.noise import GaussianNoise
+>>>
+>>> noise = GaussianNoise(sigma=0.1, seed=42)
+>>> func = SphereFunction(n_dim=2, noise=noise)
+>>> result = func([0.5, 0.5])  # Returns noisy evaluation
+
+Decaying noise over optimization:
+
+>>> noise = GaussianNoise(
+...     sigma=0.5,
+...     sigma_final=0.01,
+...     schedule="linear",
+...     total_evaluations=1000,
+...     seed=42
+... )
+>>> func = SphereFunction(n_dim=2, noise=noise)
+
+Available noise types:
+
+- GaussianNoise: Additive Gaussian noise, f(x) + N(0, sigma^2)
+- UniformNoise: Additive uniform noise, f(x) + U(low, high)
+- MultiplicativeNoise: Multiplicative noise, f(x) * (1 + N(0, sigma^2))
+"""
+
+from ._base import BaseNoise
+from ._gaussian import GaussianNoise
+from ._multiplicative import MultiplicativeNoise
+from ._uniform import UniformNoise
+
+__all__ = [
+    "BaseNoise",
+    "GaussianNoise",
+    "UniformNoise",
+    "MultiplicativeNoise",
+]

src/surfaces/noise/_base.py

@@ -0,0 +1,150 @@
+# Author: Simon Blanke
+# Email: [email protected]
+# License: MIT License
+
+"""Base class for noise layers."""
+
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional
+
+import numpy as np
+
+
+class BaseNoise(ABC):
+    """Base class for noise layers that can be applied to test functions.
+
+    Noise layers add stochastic disturbances to function evaluations,
+    useful for testing algorithm robustness to noisy observations.
+
+    Parameters
+    ----------
+    seed : int, optional
+        Random seed for reproducibility. If None, uses non-deterministic
+        random state.
+    schedule : str, optional
+        Schedule for decaying noise over evaluations. Options:
+        - None: Constant noise (default)
+        - "linear": Linear decay from initial to final
+        - "exponential": Exponential decay
+        - "cosine": Cosine annealing
+    total_evaluations : int, optional
+        Total number of evaluations for the schedule. Required if
+        schedule is set.
+
+    Attributes
+    ----------
+    last_noise : float or None
+        The noise value from the most recent apply() call.
+        None if apply() has not been called yet.
+
+    Examples
+    --------
+    >>> from surfaces.noise import GaussianNoise
+    >>> noise = GaussianNoise(sigma=0.1, seed=42)
+    >>> noisy_value = noise.apply(5.0, {"x0": 0.5})
+    >>> print(noise.last_noise)  # The noise that was added
+    """
+
+    def __init__(
+        self,
+        seed: Optional[int] = None,
+        schedule: Optional[str] = None,
+        total_evaluations: Optional[int] = None,
+    ):
+        if schedule is not None and total_evaluations is None:
+            raise ValueError("total_evaluations required when schedule is set")
+
+        if schedule is not None and schedule not in ("linear", "exponential", "cosine"):
+            raise ValueError(
+                f"schedule must be 'linear', 'exponential', or 'cosine', got '{schedule}'"
+            )
+
+        self._seed = seed
+        self._rng = np.random.default_rng(seed)
+        self._schedule = schedule
+        self._total_evaluations = total_evaluations
+        self._evaluation_count = 0
+        self.last_noise: Optional[float] = None
+
+    def _get_schedule_factor(self) -> float:
+        """Get the current schedule factor in [0, 1].
+
+        Returns 1.0 at the start (full noise) and decays toward 0.0
+        according to the schedule type.
+
+        Returns
+        -------
+        float
+            Schedule factor between 0 and 1.
+        """
+        if self._schedule is None:
+            return 1.0
+
+        progress = self._evaluation_count / self._total_evaluations
+        progress = min(1.0, progress)  # Cap at 1.0
+
+        if self._schedule == "linear":
+            return 1.0 - progress
+        elif self._schedule == "exponential":
+            # Decays to ~0.0067 at progress=1.0
+            return np.exp(-5.0 * progress)
+        elif self._schedule == "cosine":
+            # Smooth cosine decay
+            return 0.5 * (1.0 + np.cos(np.pi * progress))
+
+        return 1.0
+
+    def apply(self, value: float, params: Dict[str, Any]) -> float:
+        """Apply noise to a function value.
+
+        Parameters
+        ----------
+        value : float
+            The original function value.
+        params : dict
+            The input parameters (available for heteroscedastic noise).
+
+        Returns
+        -------
+        float
+            The noisy function value.
+        """
+        self._evaluation_count += 1
+        return self._apply_noise(value, params)
+
+    @abstractmethod
+    def _apply_noise(self, value: float, params: Dict[str, Any]) -> float:
+        """Apply noise to a value. Override in subclasses.
+
+        Parameters
+        ----------
+        value : float
+            The original function value.
+        params : dict
+            The input parameters.
+
+        Returns
+        -------
+        float
+            The noisy function value.
+        """
+        pass
+
+    def reset(self, seed: Optional[int] = None) -> None:
+        """Reset the noise layer state.
+
+        Resets the evaluation counter and random state.
+
+        Parameters
+        ----------
+        seed : int, optional
+            New seed for the random state. If None, uses the original seed.
+        """
+        self._evaluation_count = 0
+        self._rng = np.random.default_rng(seed if seed is not None else self._seed)
+        self.last_noise = None
+
+    @property
+    def evaluation_count(self) -> int:
+        """Number of times apply() has been called."""
+        return self._evaluation_count

src/surfaces/noise/_gaussian.py

@@ -0,0 +1,90 @@
+# Author: Simon Blanke
+# Email: [email protected]
+# License: MIT License
+
+"""Gaussian (additive normal) noise."""
+
+from typing import Any, Dict, Optional
+
+from ._base import BaseNoise
+
+
+class GaussianNoise(BaseNoise):
+    """Additive Gaussian noise: f(x) + N(0, sigma^2).
+
+    Adds normally distributed noise to function evaluations.
+    Supports optional scheduling to decay sigma over evaluations.
+
+    Parameters
+    ----------
+    sigma : float, default=0.1
+        Standard deviation of the Gaussian noise. This is the initial
+        value if a schedule is used.
+    sigma_final : float, optional
+        Final standard deviation when using a schedule. If None,
+        defaults to sigma (no decay in the sigma value itself,
+        but schedule factor still applies).
+    seed : int, optional
+        Random seed for reproducibility.
+    schedule : str, optional
+        Schedule for decaying noise. See BaseNoise for options.
+    total_evaluations : int, optional
+        Total evaluations for the schedule.
+
+    Attributes
+    ----------
+    last_noise : float or None
+        The noise value added in the most recent apply() call.
+
+    Examples
+    --------
+    Constant noise:
+
+    >>> noise = GaussianNoise(sigma=0.1, seed=42)
+    >>> noisy = noise.apply(5.0, {})
+    >>> print(f"Added noise: {noise.last_noise:.4f}")
+
+    Decaying noise (sigma: 0.5 -> 0.01 over 1000 evaluations):
+
+    >>> noise = GaussianNoise(
+    ...     sigma=0.5,
+    ...     sigma_final=0.01,
+    ...     schedule="linear",
+    ...     total_evaluations=1000,
+    ...     seed=42
+    ... )
+    """
+
+    def __init__(
+        self,
+        sigma: float = 0.1,
+        sigma_final: Optional[float] = None,
+        seed: Optional[int] = None,
+        schedule: Optional[str] = None,
+        total_evaluations: Optional[int] = None,
+    ):
+        super().__init__(
+            seed=seed,
+            schedule=schedule,
+            total_evaluations=total_evaluations,
+        )
+
+        if sigma < 0:
+            raise ValueError(f"sigma must be non-negative, got {sigma}")
+
+        self._sigma_initial = sigma
+        self._sigma_final = sigma_final if sigma_final is not None else sigma
+
+        if self._sigma_final < 0:
+            raise ValueError(f"sigma_final must be non-negative, got {sigma_final}")
+
+    @property
+    def sigma(self) -> float:
+        """Current sigma based on schedule progress."""
+        factor = self._get_schedule_factor()
+        return self._sigma_final + (self._sigma_initial - self._sigma_final) * factor
+
+    def _apply_noise(self, value: float, params: Dict[str, Any]) -> float:
+        """Apply Gaussian noise to the value."""
+        self.last_noise = self._rng.normal(0.0, self.sigma)
+        return value + self.last_noise

src/surfaces/noise/_multiplicative.py

@@ -0,0 +1,86 @@
+# Author: Simon Blanke
+# Email: [email protected]
+# License: MIT License
+
+"""Multiplicative noise."""
+
+from typing import Any, Dict, Optional
+
+from ._base import BaseNoise
+
+
+class MultiplicativeNoise(BaseNoise):
+    """Multiplicative Gaussian noise: f(x) * (1 + N(0, sigma^2)).
+
+    Applies noise proportional to the function value. Useful for
+    simulating relative measurement uncertainty where larger values
+    have proportionally larger noise.
+
+    Parameters
+    ----------
+    sigma : float, default=0.1
+        Standard deviation of the multiplicative factor. A value of 0.1
+        means the noise factor is typically within +/-10% of 1.0.
+        This is the initial value if a schedule is used.
+    sigma_final : float, optional
+        Final sigma when using a schedule. Defaults to sigma.
+    seed : int, optional
+        Random seed for reproducibility.
+    schedule : str, optional
+        Schedule for decaying noise. See BaseNoise for options.
+    total_evaluations : int, optional
+        Total evaluations for the schedule.
+
+    Attributes
+    ----------
+    last_noise : float or None
+        The multiplicative factor (not the final noise contribution)
+        from the most recent apply() call. The actual noise added
+        is value * last_noise.
+
+    Examples
+    --------
+    Constant multiplicative noise (+/-10%):
+
+    >>> noise = MultiplicativeNoise(sigma=0.1, seed=42)
+    >>> noisy = noise.apply(100.0, {})
+    >>> # Result is approximately 100 * (1 + small_gaussian)
+
+    Note that for values near zero, multiplicative noise has minimal
+    effect. Use GaussianNoise for additive noise that is independent
+    of the function value.
+    """
+
+    def __init__(
+        self,
+        sigma: float = 0.1,
+        sigma_final: Optional[float] = None,
+        seed: Optional[int] = None,
+        schedule: Optional[str] = None,
+        total_evaluations: Optional[int] = None,
+    ):
+        super().__init__(
+            seed=seed,
+            schedule=schedule,
+            total_evaluations=total_evaluations,
+        )
+
+        if sigma < 0:
+            raise ValueError(f"sigma must be non-negative, got {sigma}")
+
+        self._sigma_initial = sigma
+        self._sigma_final = sigma_final if sigma_final is not None else sigma
+
+        if self._sigma_final < 0:
+            raise ValueError(f"sigma_final must be non-negative, got {sigma_final}")
+
+    @property
+    def sigma(self) -> float:
+        """Current sigma based on schedule progress."""
+        factor = self._get_schedule_factor()
+        return self._sigma_final + (self._sigma_initial - self._sigma_final) * factor
+
+    def _apply_noise(self, value: float, params: Dict[str, Any]) -> float:
+        """Apply multiplicative noise to the value."""
+        self.last_noise = self._rng.normal(0.0, self.sigma)
+        return value * (1.0 + self.last_noise)