spotoptim

Sequential Parameter Optimization Toolbox

Testing & Quality

Status

About spotoptim

spotoptim is a Python toolbox for Sequential Parameter Optimization (SPO), designed for robust and efficient optimization of expensive-to-evaluate functions.

Documentation

Documentation (API) is available at: https://sequential-parameter-optimization.github.io/spotoptim/

License

spotoptim software: AGPL-3.0-or-later License

Features

Surrogate Model Based Optimization: Uses surrogate models to efficiently optimize expensive black-box functions
Multiple Acquisition Functions: Expected Improvement (EI), Predicted Mean (y), Probability of Improvement (PI)
Flexible Surrogates: Default Gaussian Process or custom Kriging surrogate
Variable Types: Support for continuous, integer, and mixed variable types
scipy-compatible: Returns OptimizeResult objects compatible with scipy.optimize

Installation

pip install spotoptim

Quick Start

import numpy as np
from spotoptim import SpotOptim

# Define objective function
def rosenbrock(X):
    X = np.atleast_2d(X)
    x, y = X[:, 0], X[:, 1]
    return (1 - x)**2 + 100 * (y - x**2)**2

# Set up optimization
bounds = [(-2, 2), (-2, 2)]

optimizer = SpotOptim(
    fun=rosenbrock,
    bounds=bounds,
    max_iter=50,
    n_initial=10,
    seed=42
)

# Run optimization
result = optimizer.optimize()

print(f"Best point: {result.x}")
print(f"Best value: {result.fun}")

Using Kriging Surrogate

SpotOptim includes a simplified Kriging (Gaussian Process) surrogate as an alternative to scikit-learn's GaussianProcessRegressor:

from spotoptim import SpotOptim, Kriging

# Create Kriging surrogate
kriging = Kriging(
    noise=1e-6,
    min_theta=-3.0,
    max_theta=2.0,
    seed=42
)

# Use with SpotOptim
optimizer = SpotOptim(
    fun=rosenbrock,
    bounds=bounds,
    surrogate=kriging,  # Use Kriging instead of default GP
    seed=42
)

result = optimizer.optimize()

API Reference

SpotOptim

Parameters:

fun (callable): Objective function to minimize
bounds (list of tuples): Bounds for each dimension as [(low, high), ...]
max_iter (int, default=20): Maximum number of optimization iterations
n_initial (int, default=10): Number of initial design points
surrogate (object, optional): Surrogate model (default: GaussianProcessRegressor)
acquisition (str, default='ei'): Acquisition function ('ei', 'y', 'pi')
var_type (list of str, optional): Variable types for each dimension
tolerance_x (float, optional): Minimum distance between points
seed (int, optional): Random seed for reproducibility
verbose (bool, default=False): Print progress information
max_surrogate_points (int, optional): Maximum number of points for surrogate fitting (default: 30; set to None to use all points)
selection_method (str, default='distant'): Point selection method ('distant' or 'best')

Methods:

optimize(X0=None): Run optimization, optionally with initial design points
plot_surrogate(i=0, j=1, show=True, **kwargs): Visualize the fitted surrogate model

Point Selection for Surrogate Training

When optimizing expensive functions with many iterations, the number of evaluated points can become large, making surrogate model training computationally expensive. SpotOptim implements an automatic point selection mechanism to address this:

Usage

optimizer = SpotOptim(
    fun=expensive_function,
    bounds=bounds,
    max_iter=100,
    n_initial=20,
    max_surrogate_points=50,  # Use only 50 points for surrogate training
    selection_method='distant',  # or 'best'
    verbose=True
)

Selection Methods

'distant' (default): Uses K-means clustering to select points that are maximally distant from each other, ensuring good space-filling properties.
'best': Clusters points and selects all points from the cluster with the best (lowest) mean objective function value, focusing on promising regions.

Benefits

Reduced computational cost: Surrogate training scales with the number of points
Maintained accuracy: Carefully selected points preserve model quality
Scalability: Enables optimization with hundreds or thousands of function evaluations

See the test suite in tests/ for detailed implementation examples, including point selection logic.

Kriging

Parameters:

noise (float, optional): Regularization parameter
kernel (str, default='gauss'): Kernel type
n_theta (int, optional): Number of theta parameters
min_theta (float, default=-3.0): Minimum log10(theta) bound
max_theta (float, default=2.0): Maximum log10(theta) bound
seed (int, optional): Random seed

Methods:

fit(X, y): Fit the model to training data
predict(X, return_std=False): Predict at new points

Visualizing Results

SpotOptim includes a plot_surrogate() method to visualize the fitted surrogate model:

# After running optimization
optimizer.plot_surrogate(
    i=0, j=1,                    # Dimensions to plot
    var_name=['x1', 'x2'],       # Variable names
    add_points=True,             # Show evaluated points
    cmap='viridis',              # Colormap
    show=True
)

The plot shows:

Top left: 3D surface of predictions
Top right: 3D surface of prediction uncertainty
Bottom left: Contour plot of predictions with evaluated points
Bottom right: Contour plot of prediction uncertainty

For higher-dimensional problems, the method visualizes a 2D slice by fixing other dimensions at their mean values.

Examples

Notebooks

See notebooks/spotoptim_tests.ipynb for interactive examples and API usage demonstrations.

Real-World Applications & Tutorials

Detailed documentation and tutorials are available in the docs/ directory and on the official documentation site.

SPOT Examples - Simple runs and visualization
Step-by-Step Tutorial - Comprehensive optimization guide

Run the test-based examples:

# Run all tests including example-based tests
uv run pytest tests/

See docs/examples.md for more details and additional examples.

Development

# Clone repository
git clone https://github.com/sequential-parameter-optimization/spotoptim.git
cd spotoptim

# Install with uv (editable, with dev dependencies)
uv sync --extra dev

# Run the fast suite (excludes slow end-to-end tests) — what CI/PRs gate on
uv run pytest tests/ -m "not slow" -n auto

# Run the full suite (everything, including slow tests)
uv run pytest tests/ -n auto

# Build package
uv build

Fast vs. full tests

Heavy end-to-end optimization tests are tagged @pytest.mark.slow (registered centrally in tests/conftest.py). The fast path skips them with -m "not slow"; the full suite and the nightly CI job run everything.

Git hooks (pre-push test gate)

A .pre-commit-config.yaml runs the fast test suite before every git push and blocks the push if any test fails. Hooks are per-clone and are not installed automatically — install them once after cloning:

uv run pre-commit install --hook-type pre-push --hook-type pre-commit

on git push → uv run pytest -m "not slow" -n auto
on git commit → ruff check + black --check on changed files

Emergency bypass (use sparingly): git push --no-verify. Note that the bare pre-commit install only wires the commit stage — the --hook-type pre-push flag is required to enable the test gate.

Release Troubleshooting

If a release fails (for example with semantic-release push/tag permission errors), use this checklist.

1) Push workflow updates

git add .github/workflows/release.yml .github/workflows/release-preflight.yml README.md
git commit -m "docs(ci): add release troubleshooting and preflight instructions"
git push origin main

2) Run and inspect workflows

# List workflows
gh workflow list

# Check latest runs
gh run list --workflow "Release Preflight" --limit 5
gh run list --workflow "Release" --limit 5

# Show detailed logs
gh run view --workflow "Release Preflight" --log
gh run view --workflow "Release" --log

for r in spotoptim spotforecast2_safe; do
    echo "== $r =="
    gh api repos/sequential-parameter-optimization/$r/actions/permissions/workflow \
        --jq '{default_workflow_permissions,can_approve_pull_request_reviews}'
    gh secret list -R sequential-parameter-optimization/$r
    gh api repos/sequential-parameter-optimization/$r/rulesets \
        --jq '.[]|{name,target,enforcement,bypass_actors}'
done

4) Required GitHub settings

Actions workflow permissions: Read and write
Token secret: SEMANTIC_RELEASE_TOKEN should exist (or rely on github.token)
Branch/ruleset policy: must allow push/tag creation by GitHub Actions (or PAT owner)

License

See LICENSE file.

References

Based on the SPOT (Sequential Parameter Optimization Toolbox) methodology.

Metadata

Release files for spotoptim 3.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for spotoptim 3.3.1
File	Size	Uploaded
spotoptim-3.3.1.tar.gz	330.3 kB	Jul 18, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for spotoptim 3.3.1
File	Interpreter	ABI	Platform	Reset
spotoptim-3.3.1-py3-none-any.whl 372.0 kB Jul 18, 2026	Python 3	none	any	Details

Total release size: 702.2 kB

Release files / spotoptim-3.3.1.tar.gz

Download URL	spotoptim-3.3.1.tar.gz
Size	330.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`fa25c9c8ab2e53e14fc4a21fe6d680e2972cda6f634f2dc50aef61086e2c654b`
BLAKE2b-256 checksum How to use checksums	`877f10271418834565aec87627b88f85555285ace3833560a236a18ca91b856f`
Upload date	Jul 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/sequential-parameter-optimization/spotoptim
Publishing commit: github.com/sequential-parameter-optimization/spotoptim/tree/c98aef2e0c0d02d4356df216a366e34c18ea9219

Workflow

Publishing configuration: github.com/sequential-parameter-optimization/spotoptim/blob/c98aef2e0c0d02d4356df216a366e34c18ea9219/.github/workflows/release.yml
Publishing logs: github.com/sequential-parameter-optimization/spotoptim/actions/runs/29664514077/attempts/1

Artifact

Subject: spotoptim-3.3.1.tar.gz
SHA-256 checksum: fa25c9c8ab2e53e14fc4a21fe6d680e2972cda6f634f2dc50aef61086e2c654b Verifying attestations

Release files / spotoptim-3.3.1-py3-none-any.whl

Download URL	spotoptim-3.3.1-py3-none-any.whl
Size	372.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`b042db2e4e6c0322e1084e6c5f7719f0ee5db051dd01ea36a03cc58494475dad`
BLAKE2b-256 checksum How to use checksums	`b0550980519ffa353ad1de91f9d04d51a7670ce517a350279bd2d60bc8a97dee`
Upload date	Jul 18, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/sequential-parameter-optimization/spotoptim
Publishing commit: github.com/sequential-parameter-optimization/spotoptim/tree/c98aef2e0c0d02d4356df216a366e34c18ea9219

Workflow

Publishing configuration: github.com/sequential-parameter-optimization/spotoptim/blob/c98aef2e0c0d02d4356df216a366e34c18ea9219/.github/workflows/release.yml
Publishing logs: github.com/sequential-parameter-optimization/spotoptim/actions/runs/29664514077/attempts/1

Artifact

Subject: spotoptim-3.3.1-py3-none-any.whl
SHA-256 checksum: b042db2e4e6c0322e1084e6c5f7719f0ee5db051dd01ea36a03cc58494475dad Verifying attestations