Base Classes & Interface#

BaseTestFunction#

The root class for all test functions in Surfaces.

class BaseTestFunction(objective=None, modifiers: List[BaseModifier] | None = None, memory=False, collect_data=True, callbacks=None, catch_errors=None)[source]#

Bases: object

Base class for all test functions in the Surfaces library.

This is the generic root class providing the template method pattern for evaluation, memory caching, data collection, callbacks, and error handling. Subclasses should inherit from one of the two intermediate bases:

BaseSingleObjectiveTestFunction for scalar objectives
BaseMultiObjectiveTestFunction for vector objectives

Parameters:

objective (str, list, or None) – Optimization direction. Interpreted by subclasses: single-objective uses "minimize"/"maximize"; multi-objective accepts a list of per-objective directions.
modifiers (list of BaseModifier, optional) – List of modifiers to apply to function evaluations. Modifiers are applied in the order they appear in the list.
memory (bool, default=False) – If True, caches evaluated positions to avoid redundant computations.
collect_data (bool, default=True) – If True, collects evaluation data including search_data, best_score, best_params, n_evaluations, and total_time.
callbacks (callable or list of callables, optional) – Function(s) called after each evaluation with the record dict.
catch_errors (dict, optional) – Dictionary mapping exception types to return values. Use … (Ellipsis) as a catch-all key for any unmatched exceptions.

Examples

>>> func = SphereFunction(n_dim=2)
>>> func({"x0": 1.0, "x1": 2.0})      # dict input
>>> func(np.array([1.0, 2.0]))        # array input
>>> func([1.0, 2.0])                  # list input

f_global: float | None = None[source]#

x_global: ndarray | None = None[source]#

CallbackType[source]#: alias of Callable[[Dict[str, Any]], None] | List[Callable[[Dict[str, Any]], None]]

property search_space: Dict[str, Any][source]#: Search space for this function (read-only public API).

property spec[source]#: Function characteristics (SpecAccessor).

property data[source]#: Evaluation data (DataAccessor).

property callbacks[source]#: Callback management (CallbackAccessor).

property modifiers[source]#: Modifier management (ModifierAccessor).

property memory[source]#: Memory cache management (MemoryAccessor).

property errors[source]#: Error handler management (ErrorAccessor).

property meta[source]#: Function metadata (MetaAccessor).

property plot[source]#: Access plotting methods for this function.

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

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

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

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[source]#: Reset all state including collected data and memory cache.

batch(X: ArrayLike) → ArrayLike[source]#

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.

Algebraic Base Classes#

AlgebraicFunction#

Base class for algebraic (mathematical) test functions.

class AlgebraicFunction(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)[source]#

Bases: BaseSingleObjectiveTestFunction

Base class for algebraic optimization test functions.

Algebraic functions are defined by closed-form analytical expressions, as opposed to data-driven (ML) or externally-defined (CEC/BBOB) functions.

Parameters:

objective (str, default="minimize") – Either “minimize” or “maximize”.
modifiers (list of BaseModifier, optional) – List of modifiers to apply to function evaluations.

Examples

>>> func = SphereFunction(n_dim=2)
>>> func({"x0": 0.0, "x1": 0.0})
>>> func(np.array([0.0, 0.0]))

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

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[source]#

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[source]#: Callback management (CallbackAccessor).

property data[source]#: Evaluation data (DataAccessor).

property errors[source]#: Error handler management (ErrorAccessor).

property memory[source]#: Memory cache management (MemoryAccessor).

property meta[source]#: Function metadata (MetaAccessor).

property modifiers[source]#: Modifier management (ModifierAccessor).

property plot[source]#: Access plotting methods for this function.

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

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[source]#: Reset all state including collected data and memory cache.

property search_space: Dict[str, Any][source]#: Search space for this function (read-only public API).

property spec[source]#: Function characteristics (SpecAccessor).

BBOBFunction#

Base class for BBOB (Black-Box Optimization Benchmarking) functions.

class BBOBFunction(n_dim: int = 10, instance: int = 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)[source]#

Bases: AlgebraicFunction

Base class for BBOB benchmark functions.

BBOB functions feature: - Search domain of [-5, 5]^D - Random optimal location x* within the domain - Random optimal value f* from Cauchy distribution (clipped to [-1000, 1000]) - Transformations: T_osz (oscillation), T_asy (asymmetry), rotations - Instance-based: different instances have different random transformations

Parameters:

n_dim (int, default=10) – Number of dimensions. Common values: 2, 3, 5, 10, 20, 40.
instance (int, default=1) – Instance number (1-15 in standard BBOB). Controls random seed for generating optimal location, optimal value, and transformation matrices.
objective (str, default="minimize") – Either “minimize” or “maximize”.
modifiers (list of BaseModifier, optional) – List of modifiers to apply to function evaluations.

func_id[source]#

Function ID (1-24), set by subclass.

Type:: int

x_opt[source]#

Optimal location in the search space.

Type:: np.ndarray

f_opt[source]#

Optimal function value.

Type:: float

property func_id: int | None[source]#: Function ID (1-24) within BBOB suite.

property f_global: float[source]#: Global optimum value for this function instance.

property x_global: ndarray | None[source]#: Global optimum location for this function instance.

property x_opt: ndarray[source]#: Optimal location in the search space.

property f_opt: float[source]#: Optimal function value.

property Q: ndarray[source]#: First rotation matrix (orthogonal).

property R: ndarray[source]#: Second rotation matrix (orthogonal).

lambda_alpha(alpha: float) → ndarray[source]#

Generate diagonal conditioning matrix with condition number alpha.

Parameters:: alpha (float) – Condition number (ratio of largest to smallest eigenvalue).
Returns:: Diagonal matrix of shape (n_dim, n_dim).
Return type:: np.ndarray

t_osz(x: ndarray) → ndarray[source]#

Apply oscillation transformation T_osz.

Creates smooth oscillations around the identity to break symmetry.

Parameters:: x (np.ndarray) – Input vector.
Returns:: Transformed vector.
Return type:: np.ndarray

t_asy(x: ndarray, beta: float) → ndarray[source]#

Apply asymmetry transformation T_asy^beta.

Breaks symmetry by applying different scaling to positive values.

Parameters:

x (np.ndarray) – Input vector.
beta (float) – Asymmetry parameter.

Returns:

Transformed vector.

Return type:

np.ndarray

f_pen(x: ndarray) → float[source]#

Boundary penalty function.

Penalizes solutions outside [-5, 5]^D.

Parameters:: x (np.ndarray) – Input vector.
Returns:: Penalty value (0 if within bounds).
Return type:: float

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

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[source]#

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[source]#: Callback management (CallbackAccessor).

property data[source]#: Evaluation data (DataAccessor).

property errors[source]#: Error handler management (ErrorAccessor).

property memory[source]#: Memory cache management (MemoryAccessor).

property meta[source]#: Function metadata (MetaAccessor).

property modifiers[source]#: Modifier management (ModifierAccessor).

property plot[source]#: Access plotting methods for this function.

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

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[source]#: Reset all state including collected data and memory cache.

property search_space: Dict[str, Any][source]#: Search space for this function (read-only public API).

property spec[source]#: Function characteristics (SpecAccessor).

CECFunction#

Base class for CEC competition benchmark functions.

class CECFunction(n_dim: int = 10, 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)[source]#

Bases: AlgebraicFunction

Base class for all CEC competition benchmark functions.

CEC (IEEE Congress on Evolutionary Computation) benchmark functions are shifted and/or rotated versions of classical optimization test functions. They are widely used in the optimization research community for comparing algorithm performance.

This base class provides: - Data loading (shift vectors, rotation matrices, shuffle indices) - Transformation methods (shift, rotate, oscillation, asymmetric) - Common interface for all CEC years

Subclasses must define: - func_id: Function identifier within the CEC suite - data_prefix: Prefix for data files (e.g., “cec2014”) - f_global: Global optimum value (via property or formula) - supported_dims: Tuple of supported dimensions

Parameters:

n_dim (int) – Number of dimensions.
objective (str, default="minimize") – Either “minimize” or “maximize”.
modifiers (list of BaseModifier, optional) – List of modifiers to apply to function evaluations.

func_id[source]#

Function ID within the CEC suite.

Type:: int

f_global[source]#

Global optimum value.

Type:: float

x_global[source]#

Global optimum location (typically the shift vector).

Type:: np.ndarray

property func_id: int | None[source]#: Function ID within the CEC suite.

abstract property f_global: float[source]#: Global optimum value for this function.

property x_global: ndarray | None[source]#: Global optimum location (the shift vector).

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

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[source]#

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[source]#: Callback management (CallbackAccessor).

property data[source]#: Evaluation data (DataAccessor).

property errors[source]#: Error handler management (ErrorAccessor).

property memory[source]#: Memory cache management (MemoryAccessor).

property meta[source]#: Function metadata (MetaAccessor).

property modifiers[source]#: Modifier management (ModifierAccessor).

property plot[source]#: Access plotting methods for this function.

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

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[source]#: Reset all state including collected data and memory cache.

property search_space: Dict[str, Any][source]#: Search space for this function (read-only public API).

property spec[source]#: Function characteristics (SpecAccessor).

CEC2013Function#

class CEC2013Function(n_dim: int = 10, 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)[source]#

Bases: CECFunction

Base class for CEC 2013 benchmark functions.

CEC 2013 functions are shifted and/or rotated versions of classical optimization test functions. Each function has: - A function ID (1-28) - A global optimum value f* = -1400 + (func_id - 1) * 100 - Search bounds of [-100, 100]^D - Support for dimensions: 2, 5, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100

Parameters:

n_dim (int, default=10) – Number of dimensions. Supported: 2, 5, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100.
objective (str, default="minimize") – Either “minimize” or “maximize”.
sleep (float, default=0) – Artificial delay in seconds added to each evaluation.

func_id[source]#

Function ID (1-28), set by subclass.

Type:: int

shift_index[source]#

Which shift vector to use (1-10 available in data files).

Type:: int

uses_rotation[source]#

Whether to apply rotation in shift_rotate transformation.

Type:: bool

f_global[source]#

Global optimum value.

Type:: float

References

Liang, J. J., Qu, B. Y., Suganthan, P. N., & Hernandez-Diaz, A. G. (2013). Problem definitions and evaluation criteria for the CEC 2013 special session on real-parameter optimization.

property f_global: float[source]#

Global optimum value for this function.

CEC 2013 formula: f* = -1400 + (func_id - 1) * 100

property x_global: ndarray | None[source]#: Global optimum location (the shift vector).

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

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[source]#

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[source]#: Callback management (CallbackAccessor).

property data[source]#: Evaluation data (DataAccessor).

property errors[source]#: Error handler management (ErrorAccessor).

property func_id: int | None[source]#: Function ID within the CEC suite.

property memory[source]#: Memory cache management (MemoryAccessor).

property meta[source]#: Function metadata (MetaAccessor).

property modifiers[source]#: Modifier management (ModifierAccessor).

property plot[source]#: Access plotting methods for this function.

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

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[source]#: Reset all state including collected data and memory cache.

property search_space: Dict[str, Any][source]#: Search space for this function (read-only public API).

property spec[source]#: Function characteristics (SpecAccessor).

CEC2014Function#

class CEC2014Function(n_dim: int = 10, 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)[source]#

Bases: CECFunction

Base class for CEC 2014 benchmark functions.

CEC 2014 functions are shifted and/or rotated versions of classical optimization test functions. Each function has: - A function ID (1-30) - A global optimum value f* = func_id * 100 - Search bounds of [-100, 100]^D - Support for dimensions: 10, 20, 30, 50, 100

Parameters:

n_dim (int, default=10) – Number of dimensions. Supported: 10, 20, 30, 50, 100.
objective (str, default="minimize") – Either “minimize” or “maximize”.
sleep (float, default=0) – Artificial delay in seconds added to each evaluation.

func_id[source]#

Function ID (1-30), set by subclass.

Type:: int

f_global[source]#

Global optimum value (func_id * 100).

Type:: float

References

Liang, J. J., Qu, B. Y., & Suganthan, P. N. (2013). Problem definitions and evaluation criteria for the CEC 2014 special session and competition on single objective real-parameter numerical optimization.

property f_global: float[source]#

Global optimum value for this function.

CEC 2014 formula: f* = func_id * 100

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

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[source]#

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[source]#: Callback management (CallbackAccessor).

property data[source]#: Evaluation data (DataAccessor).

property errors[source]#: Error handler management (ErrorAccessor).

property func_id: int | None[source]#: Function ID within the CEC suite.

property memory[source]#: Memory cache management (MemoryAccessor).

property meta[source]#: Function metadata (MetaAccessor).

property modifiers[source]#: Modifier management (ModifierAccessor).

property plot[source]#: Access plotting methods for this function.

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

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[source]#: Reset all state including collected data and memory cache.

property search_space: Dict[str, Any][source]#: Search space for this function (read-only public API).

property spec[source]#: Function characteristics (SpecAccessor).

property x_global: ndarray | None[source]#: Global optimum location (the shift vector).

CEC2017Function#

class CEC2017Function(n_dim: int = 10, 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)[source]#

Bases: CECFunction

Base class for CEC 2017 benchmark functions.

CEC 2017 functions are shifted and/or rotated versions of classical optimization test functions. Each function has: - A function ID (1-30) - A global optimum value f* = func_id * 100 - Search bounds of [-100, 100]^D - Support for dimensions: 2, 10, 20, 30, 50, 100

Note: F2 has been deprecated from the CEC 2017 benchmark suite.

Parameters:

n_dim (int, default=10) – Number of dimensions. Supported: 2, 10, 20, 30, 50, 100.
objective (str, default="minimize") – Either “minimize” or “maximize”.
sleep (float, default=0) – Artificial delay in seconds added to each evaluation.

func_id[source]#

Function ID (1-30), set by subclass.

Type:: int

f_global[source]#

Global optimum value (func_id * 100).

Type:: float

References

Awad, N. H., Ali, M. Z., Liang, J. J., Qu, B. Y., & Suganthan, P. N. (2016). Problem definitions and evaluation criteria for the CEC 2017 special session and competition on single objective bound constrained real-parameter numerical optimization.

property f_global: float[source]#

Global optimum value for this function.

CEC 2017 formula: f* = func_id * 100

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

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[source]#

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[source]#: Callback management (CallbackAccessor).

property data[source]#: Evaluation data (DataAccessor).

property errors[source]#: Error handler management (ErrorAccessor).

property func_id: int | None[source]#: Function ID within the CEC suite.

property memory[source]#: Memory cache management (MemoryAccessor).

property meta[source]#: Function metadata (MetaAccessor).

property modifiers[source]#: Modifier management (ModifierAccessor).

property plot[source]#: Access plotting methods for this function.

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

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[source]#: Reset all state including collected data and memory cache.

property search_space: Dict[str, Any][source]#: Search space for this function (read-only public API).

property spec[source]#: Function characteristics (SpecAccessor).

property x_global: ndarray | None[source]#: Global optimum location (the shift vector).

Machine Learning Base Classes#

MachineLearningFunction#

Base class for machine learning hyperparameter optimization functions.

class MachineLearningFunction(objective: str = 'maximize', 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, use_surrogate: bool = False, **kwargs: Any)[source]#

Bases: BaseSingleObjectiveTestFunction

Base class for machine learning hyperparameter optimization test functions.

ML functions evaluate model performance based on hyperparameter configurations. They naturally return score values where higher is better.

Parameters:

objective (str, default="maximize") – Either “minimize” or “maximize”.
modifiers (list of BaseModifier, optional) – List of modifiers to apply to function evaluations.
use_surrogate (bool, default=False) – If True and a pre-trained surrogate exists, use it for fast evaluation. Falls back to real evaluation if no surrogate is available.

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

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[source]#

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[source]#: Callback management (CallbackAccessor).

property data[source]#: Evaluation data (DataAccessor).

property errors[source]#: Error handler management (ErrorAccessor).

property memory[source]#: Memory cache management (MemoryAccessor).

property meta[source]#: Function metadata (MetaAccessor).

property modifiers[source]#: Modifier management (ModifierAccessor).

property plot[source]#: Access plotting methods for this function.

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

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[source]#: Reset all state including collected data and memory cache.

property search_space: Dict[str, Any][source]#: Search space for this function (read-only public API).

property spec[source]#: Function characteristics (SpecAccessor).

BaseTabular#

Base class for tabular data ML functions.

BaseImage#

Base class for image data ML functions.

BaseTimeSeries#

Base class for time series ML functions.

Engineering Base Classes#

EngineeringFunction#

Base class for engineering design optimization problems with constraints.