Surfaces

Black-box optimization test functions for benchmarking

Surfaces provides a curated collection of optimization test functions for benchmarking gradient-free and black-box optimizers. It includes classical mathematical benchmarks, N-dimensional scalable functions, and ML-model-accelerated surrogates, all accessible through a minimal, plug-and-play API.

Features#

What makes Surfaces ideal for optimization benchmarking.

|n_total_functions|+ Test Functions

Classic optimization functions from the literature, ML-based functions, and engineering benchmarks.

Explore all function categories

ML-Based Functions

Test functions based on real machine learning models: hyperparameter tuning as optimization benchmark.

K-Neighbors, Gradient Boosting

scipy Integration

Convert any function to scipy.optimize format with to_scipy() for seamless integration.

Works with scipy optimizers

Flexible Evaluation

Call functions with dictionaries, keyword arguments, numpy arrays, or batch evaluation.

Multiple evaluation interfaces

Loss or Score

Every function supports both minimization (loss) and maximization (score) modes.

Metric handling

Built-in Visualization

Plotly-based surface plots and heatmaps for 2D function visualization.

Visualization tools

Function Categories#

Surfaces provides functions in three main categories, each with a consistent interface.

Algebraic Functions (24)

Classic test functions from the optimization literature with known global optima and analytical formulas.

1D: 1 functions
2D: 18 functions
N-D: 5 scalable functions

Explore algebraic functions

Machine Learning Functions (21)

Test functions based on real ML model training tasks, providing realistic hyperparameter optimization landscapes.

Classification: Tabular, Image, Time Series
Regression: Tabular models
Forecasting: Time series

Explore ML functions

Engineering Functions (5)

Real-world constrained engineering design optimization problems with physical meaning.

Welded Beam, Pressure Vessel
Tension-Compression Spring
Cantilever Beam, Three-Bar Truss

Explore engineering functions

Quick Install#

$ pip install surfaces

$ pip install surfaces[dev,test]

Quick Example#

Get started in just a few lines of code:

from surfaces.test_functions.algebraic import SphereFunction

# Create a 3-dimensional Sphere function
func = SphereFunction(n_dim=3)

# Evaluate with a dictionary
result = func({"x0": 1.0, "x1": 2.0, "x2": 3.0})
print(f"Loss: {result}")  # Loss: 14.0

# Get the default search space
search_space = func.search_space()
# {"x0": array(...), "x1": array(...), "x2": array(...)}

from surfaces.test_functions.algebraic import RosenbrockFunction
from scipy.optimize import minimize

# Create the test function
func = RosenbrockFunction(n_dim=5)

# Convert to scipy format
objective, bounds, x0 = func.to_scipy()

# Run scipy optimizer
result = minimize(objective, x0, bounds=bounds, method='L-BFGS-B')
print(f"Optimal x: {result.x}")
print(f"Minimum value: {result.fun}")

from surfaces.test_functions.machine_learning import KNeighborsClassifierFunction

# Create an ML-based test function
func = KNeighborsClassifierFunction()

# Evaluate with hyperparameters
score = func({
    "n_neighbors": 5,
    "weights": "distance",
    "p": 2
})
print(f"Accuracy: {score}")

# Get the hyperparameter search space
search_space = func.search_space()