SphereFunction

class SphereFunction(n_dim: int = 2, A: float = 1, objective: str = 'minimize', modifiers: List[BaseModifier] | None = None, memory: bool = False, collect_data: bool = True, callbacks: Callable | List[Callable] | None = None, catch_errors: Dict[type, float] | None = None)

Sphere N-dimensional test function.

A continuous, convex, and unimodal function. It is the simplest N-dimensional optimization test function.

The function is defined as:

\[f(\vec{x}) = A \sum_{i=1}^{n} x_i^2\]

where \(A = 1\) by default.

The global minimum is \(f(\vec{0}) = 0\).

Parameters:

• n_dim (int) – Number of dimensions.

• A (float, default=1) – Scaling parameter.

• metric (str, default="score") – Either “loss” (minimize) or “score” (maximize).

• modifiers (list of BaseModifier, optional) – List of modifiers to apply to function evaluations.

• validate (bool, default=True) – Whether to validate parameters against the search space.

n_dim

Number of dimensions.

Type:

int

Examples

>>> from surfaces.test_functions import SphereFunction
>>> func = SphereFunction(n_dim=3)
>>> result = func({"x0": 0.0, "x1": 0.0, "x2": 0.0})
>>> abs(result) < 1e-10
True
>>> len(func.search_space)
3

__call__(params: Dict[str, Any] | ndarray | list | tuple | None = None, **kwargs)

Evaluate the objective function.

Args:

params: Parameter values as dict, array, list, or tuple **kwargs: Parameters as keyword arguments (only with dict input)

Returns:

The objective function value

batch(X: ArrayLike) → ArrayLike

Evaluate multiple parameter sets in a single call.

Parameters:

X (ArrayLike) – 2D array of shape (n_points, n_dim) where each row is a parameter set.

Returns:

1D array of shape (n_points,) with evaluation results.

Return type:

ArrayLike

Raises:

• NotImplementedError – If the function does not implement _batch_objective.

• ValueError – If X has wrong number of dimensions or wrong n_dim.

property callbacks

Callback management (CallbackAccessor).

property data

Evaluation data (DataAccessor).

property errors

Error handler management (ErrorAccessor).

property memory

Memory cache management (MemoryAccessor).

property meta

Function metadata (MetaAccessor).

property modifiers

Modifier management (ModifierAccessor).

property plot

Access plotting methods for this function.

pure(params: Dict[str, Any] | ndarray | list | tuple | None = None, **kwargs)

Evaluate the function without modifiers.

Returns the true (deterministic) function value, bypassing any configured modifiers. Does not update search_data, n_evaluations, or callbacks. Ignores memory caching.

Parameters:

• params (dict, array, list, or tuple) – Parameter values to evaluate.

• **kwargs (dict) – Parameters as keyword arguments.

Returns:

The true function value without modifiers, with direction applied.

Return type:

float or np.ndarray

reset() → None

Reset all state including collected data and memory cache.

property search_space: Dict[str, Any]

Search space for this function (read-only public API).

property spec

Function characteristics (SpecAccessor).