Metadata-Version: 2.3
Name: spotoptim
Version: 0.2.1
Summary: Sequential Parameter Optimization Toolbox
Author: bartzbeielstein
Author-email: bartzbeielstein <32470350+bartzbeielstein@users.noreply.github.com>
License: AGPL-3.0-or-later
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: numpy>=1.24.3
Requires-Dist: scipy>=1.10.1
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: jupyter>=1.1.1
Requires-Dist: matplotlib>=3.10.7
Requires-Dist: pandas>=2.1.0
Requires-Dist: requests>=2.32.3
Requires-Dist: torch>=2.9.1
Requires-Dist: tensorboard>=2.20.0
Requires-Dist: tabulate>=0.9.0
Requires-Dist: xgboost>=3.1.1
Requires-Dist: seaborn>=0.13.2
Requires-Dist: spotdesirability>=0.0.1
Requires-Dist: statsmodels>=0.14.6
Requires-Dist: dill>=0.4.1
Requires-Dist: flake8>=7.3.0
Requires-Dist: pytest>=7.4.0 ; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0 ; extra == 'dev'
Requires-Dist: black>=24.1.0 ; extra == 'dev'
Requires-Dist: isort>=5.13.0 ; extra == 'dev'
Requires-Dist: ruff>=0.3.0 ; extra == 'dev'
Requires-Dist: safety>=3.0.0 ; extra == 'dev'
Requires-Dist: bandit>=1.8.0 ; extra == 'dev'
Requires-Dist: quartodoc>=0.11.1 ; extra == 'docs'
Requires-Dist: griffe>=1.7.3 ; extra == 'docs'
Requires-Dist: jupyter>=1.1.1 ; extra == 'docs'
Requires-Dist: colorama>=0.4.6 ; extra == 'docs'
Requires-Python: >=3.13
Provides-Extra: dev
Provides-Extra: docs
Description-Content-Type: text/markdown

<div align="left">
  <img src="https://raw.githubusercontent.com/sequential-parameter-optimization/spotoptim/main/img/spotLogo.png" alt="spotoptim Logo" width="300">
</div>


# spotoptim

Sequential Parameter Optimization Toolbox


[![Python Version](https://img.shields.io/badge/python-3.14%2B-blue)](https://www.python.org/downloads/)
[![PyPI Version](https://img.shields.io/pypi/v/spotoptim)](https://pypi.org/project/spotoptim/)
[![PyPI Downloads](https://img.shields.io/pypi/dm/spotoptim)](https://pypi.org/project/spotoptim/)
[![Total Downloads](https://static.pepy.tech/badge/spotoptim)](https://pepy.tech/project/spotoptim)
[![License](https://img.shields.io/github/license/sequential-parameter-optimization/spotoptim)](LICENSE)

### Testing & Quality

[![Build Status](https://img.shields.io/github/actions/workflow/status/sequential-parameter-optimization/spotoptim/ci.yml?branch=main&label=Tests)](https://github.com/sequential-parameter-optimization/spotoptim/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/sequential-parameter-optimization/spotoptim/branch/main/graph/badge.svg)](https://codecov.io/gh/sequential-parameter-optimization/spotoptim)
[![REUSE status](https://api.reuse.software/badge/github.com/sequential-parameter-optimization/spotoptim)](https://api.reuse.software/info/github.com/sequential-parameter-optimization/spotoptim)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/sequential-parameter-optimization/spotoptim/badge)](https://scorecard.dev/viewer/?uri=github.com/sequential-parameter-optimization/spotoptim)
[![Documentation](https://img.shields.io/badge/docs-passing-brightgreen)](https://sequential-parameter-optimization.github.io/spotoptim/)
[![GitHub Release](https://img.shields.io/github/v/release/sequential-parameter-optimization/spotoptim)](https://github.com/sequential-parameter-optimization/spotoptim/releases)

### Status

[![Maintenance](https://img.shields.io/badge/maintenance-active-green)](https://github.com/sequential-parameter-optimization/spotoptim)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

## 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/](https://sequential-parameter-optimization.github.io/spotoptim/)

## License

`spotoptim` software: [AGPL-3.0-or-later License](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

```bash
pip install spotoptim
```

## Quick Start

```python
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:

```python
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: None, 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

```python
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

1. **'distant' (default)**: Uses K-means clustering to select points that are maximally distant from each other, ensuring good space-filling properties.

2. **'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:

```python
# 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](docs/examples.md) - Simple runs and visualization
- [Step-by-Step Tutorial](https://sequential-parameter-optimization.github.io/spotoptim/qmd/spot_step_by_step.html) - Comprehensive optimization guide

Run the test-based examples:
```bash
# Run all tests including example-based tests
uv run pytest tests/
```

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

## Development

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

# Install with uv
uv pip install -e .

# Run tests
uv run pytest tests/

# Build package
uv build
```

## Release Troubleshooting

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

### 1) Push workflow updates

```bash
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

```bash
# 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
```

### 3) Compare release-related settings between repositories

```bash
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.
