Metadata-Version: 2.4
Name: surfaces-surrogates
Version: 0.0.1
Summary: Pre-trained ONNX surrogate models for the surfaces library
Author-email: Simon Blanke <simon.blanke@yahoo.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/SimonBlanke/surfaces-surrogates
Project-URL: Repository, https://github.com/SimonBlanke/surfaces-surrogates
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: train
Requires-Dist: surfaces>=0.9.0; extra == "train"
Requires-Dist: scikit-learn; extra == "train"
Requires-Dist: onnxruntime>=1.16.0; extra == "train"
Requires-Dist: skl2onnx>=1.16.0; extra == "train"
Requires-Dist: rich>=13.0.0; extra == "train"
Provides-Extra: dashboard
Requires-Dist: surfaces-surrogates[train]; extra == "dashboard"
Requires-Dist: streamlit>=1.28.0; extra == "dashboard"
Requires-Dist: plotly>=5.0.0; extra == "dashboard"
Requires-Dist: pandas>=1.3.0; extra == "dashboard"
Provides-Extra: test
Requires-Dist: surfaces-surrogates[train]; extra == "test"
Requires-Dist: pytest>=7.0.0; extra == "test"
Dynamic: license-file

# surfaces-surrogates

Pre-trained ONNX surrogate models for the [surfaces](https://github.com/SimonBlanke/Surfaces) library.

Surrogate models approximate computationally expensive ML hyperparameter optimization test functions. Instead of running real cross-validation (seconds to minutes per evaluation), the surrogate returns a prediction in under a millisecond via ONNX inference.

## Installation

```bash
pip install surfaces-surrogates
```

For use with the surfaces library, install the `surrogates` extra which includes `onnxruntime`:

```bash
pip install surfaces[surrogates]
```

## Usage

Surrogates are used transparently through the surfaces library:

```python
from surfaces.test_functions.machine_learning import KNeighborsClassifierFunction

func = KNeighborsClassifierFunction(use_surrogate=True)
score = func({"n_neighbors": 5, "algorithm": "auto"})
```

The surrogate models can also be loaded directly:

```python
from surfaces_surrogates.models import get_model_path

path = get_model_path("k_neighbors_classifier")
```

## Available Models

| Model | R2 | Fidelity-Aware |
|---|---|---|
| decision_tree_classifier | 0.995 | Yes |
| k_neighbors_regressor | 0.988 | Yes |
| k_neighbors_classifier | 0.966 | Yes |
| gradient_boosting_regressor | n/a | No |
| svm_regressor | 0.351 | Yes |

## Training New Models

To retrain or extend surrogate models, install the training dependencies:

```bash
pip install surfaces-surrogates[train]
```

Then use the training script:

```bash
python scripts/train_surrogates.py --status    # show current state
python scripts/train_surrogates.py             # train new/stale models
python scripts/train_surrogates.py --force     # retrain everything
```

## License

MIT
