Noise#

Base Class#

class BaseNoise(seed: int | None = None, schedule: str | None = None, total_evaluations: int | None = None)[source]#

Bases: BaseModifier

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.

last_noise[source]#

The noise value from the most recent apply() call. None if apply() has not been called yet.

Type:

float or None

Examples

>>> from surfaces.modifiers 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
apply(value: float, params: Dict[str, Any], context: Dict[str, Any]) → float[source]#

Apply noise to a function value.

Parameters:

  • value (float) – The original function value.

  • params (dict) – The input parameters (available for heteroscedastic noise).

  • context (dict) – Context information (unused by noise modifiers).

Returns:

The noisy function value.

Return type:

float

reset(seed: int | None = None) → None[source]#

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.

property evaluation_count: int[source]#

Number of times apply() has been called.

Noise Types#

GaussianNoise#

Additive Gaussian noise: f(x) + N(0, sigma^2)

class GaussianNoise(sigma: float = 0.1, sigma_final: float | None = None, seed: int | None = None, schedule: str | None = None, total_evaluations: int | None = None)[source]#

Bases: 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.

last_noise[source]#

The noise value added in the most recent apply() call.

Type:

float or None

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
... )
property sigma: float[source]#

Current sigma based on schedule progress.

apply(value: float, params: Dict[str, Any], context: Dict[str, Any]) → float[source]#

Apply noise to a function value.

Parameters:

  • value (float) – The original function value.

  • params (dict) – The input parameters (available for heteroscedastic noise).

  • context (dict) – Context information (unused by noise modifiers).

Returns:

The noisy function value.

Return type:

float

property evaluation_count: int[source]#

Number of times apply() has been called.

reset(seed: int | None = None) → None[source]#

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.

UniformNoise#

Additive uniform noise: f(x) + U(low, high)

class UniformNoise(low: float = -0.1, high: float = 0.1, low_final: float | None = None, high_final: float | None = None, seed: int | None = None, schedule: str | None = None, total_evaluations: int | None = None)[source]#

Bases: BaseNoise

Additive uniform noise: f(x) + U(low, high).

Adds uniformly distributed noise within a specified range. Supports optional scheduling to decay the noise range over evaluations.

Parameters:

  • low (float, default=-0.1) – Lower bound of the uniform distribution. Initial value if schedule is used.

  • high (float, default=0.1) – Upper bound of the uniform distribution. Initial value if schedule is used.

  • low_final (float, optional) – Final lower bound when using a schedule. Defaults to low.

  • high_final (float, optional) – Final upper bound when using a schedule. Defaults to high.

  • 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.

last_noise[source]#

The noise value added in the most recent apply() call.

Type:

float or None

Examples

Constant noise in [-0.1, 0.1]:

>>> noise = UniformNoise(low=-0.1, high=0.1, seed=42)
>>> noisy = noise.apply(5.0, {})

Symmetric noise (convenience):

>>> noise = UniformNoise(low=-0.5, high=0.5)

Decaying noise range:

>>> noise = UniformNoise(
...     low=-0.5, high=0.5,
...     low_final=-0.01, high_final=0.01,
...     schedule="linear",
...     total_evaluations=1000
... )
property low: float[source]#

Current lower bound based on schedule progress.

property high: float[source]#

Current upper bound based on schedule progress.

apply(value: float, params: Dict[str, Any], context: Dict[str, Any]) → float[source]#

Apply noise to a function value.

Parameters:

  • value (float) – The original function value.

  • params (dict) – The input parameters (available for heteroscedastic noise).

  • context (dict) – Context information (unused by noise modifiers).

Returns:

The noisy function value.

Return type:

float

property evaluation_count: int[source]#

Number of times apply() has been called.

reset(seed: int | None = None) → None[source]#

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.

MultiplicativeNoise#

Multiplicative noise: f(x) * (1 + N(0, sigma^2))

class MultiplicativeNoise(sigma: float = 0.1, sigma_final: float | None = None, seed: int | None = None, schedule: str | None = None, total_evaluations: int | None = None)[source]#

Bases: 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.

last_noise[source]#

The multiplicative factor (not the final noise contribution) from the most recent apply() call. The actual noise added is value * last_noise.

Type:

float or None

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.

property sigma: float[source]#

Current sigma based on schedule progress.

apply(value: float, params: Dict[str, Any], context: Dict[str, Any]) → float[source]#

Apply noise to a function value.

Parameters:

  • value (float) – The original function value.

  • params (dict) – The input parameters (available for heteroscedastic noise).

  • context (dict) – Context information (unused by noise modifiers).

Returns:

The noisy function value.

Return type:

float

property evaluation_count: int[source]#

Number of times apply() has been called.

reset(seed: int | None = None) → None[source]#

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.