Get Started#

This guide walks you through your first steps with Surfaces in under 5 minutes.

What is Surfaces?#

Surfaces is a Python library that provides standardized test functions for optimization algorithm benchmarking. These functions have known properties (global optima, landscapes, difficulty) that make them ideal for:

  • Testing new optimization algorithms

  • Comparing algorithm performance

  • Educational purposes

  • Prototyping optimization pipelines

Quick Install#

pip install surfaces

Why Surfaces?#

Curated Test Functions

Not just a random collection. Surfaces provides carefully selected test functions from established benchmarks like CEC and BBOB, plus real-world ML and engineering problems.

Curated Test Functions
Plug & Play Integration

Works out of the box with scipy, Optuna, SMAC, Ray Tune, Gradient-Free-Optimizers, and Hyperactive. No adapters needed.

Plug & Play Integration
Machine Learning Accelerated

Pre-trained surrogate models let you benchmark expensive ML hyperparameter optimization problems instantly.

Machine Learning Accelerated
Minimal Dependencies

Core installation requires only numpy. Add optional features like ML functions or visualization only when you need them.

Minimal Dependencies

Your First Test Function#

Let’s evaluate the classic Sphere function:

from surfaces.test_functions.algebraic import SphereFunction

# Create a 2D Sphere function
func = SphereFunction(n_dim=2)

# Evaluate at a point
loss = func({"x0": 1.0, "x1": 2.0})
print(f"f(1, 2) = {loss}")  # Output: 5.0

# The global minimum is at (0, 0)
optimal = func({"x0": 0.0, "x1": 0.0})
print(f"f(0, 0) = {optimal}")  # Output: 0.0

Next Steps#