Metadata-Version: 2.4
Name: ennbo
Version: 0.3.10
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Requires-Dist: pytest>=8.0 ; extra == 'dev'
Requires-Dist: pytest-testmon>=2.0 ; extra == 'dev'
Requires-Dist: ruff>=0.4 ; extra == 'dev'
Requires-Dist: nbmake>=1.5 ; extra == 'dev'
Requires-Dist: nds>=0.4.3 ; extra == 'dev'
Requires-Dist: pandas>=2.0 ; extra == 'dev'
Requires-Dist: matplotlib>=3.8 ; extra == 'dev'
Requires-Dist: numpy>=1.26.4,<2.0.0 ; extra == 'with-deps'
Requires-Dist: torch>=2.5.1 ; extra == 'with-deps'
Requires-Dist: gpytorch>=1.13 ; extra == 'with-deps'
Requires-Dist: faiss-cpu>=1.9.0 ; extra == 'with-deps'
Requires-Dist: scipy>=1.15.3 ; extra == 'with-deps'
Provides-Extra: dev
Provides-Extra: with-deps
License-File: LICENSE
Summary: Epistemic Nearest Neighbors
Author-email: YUBO Lab <david.sweet@yu.edu>
Requires-Python: >=3.11
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/yubo-research/enn
Project-URL: Source, https://github.com/yubo-research/enn

# Epistemic Nearest Neighbors
A fast, alternative surrogate for Bayesian optimization

ENN estimates a function's value and associated epistemic uncertainty using a K-Nearest Neighbors model. Queries take $O(N lnK)$ time, where $N$ is the number of observations available for KNN lookups. Compare to an exact GP, which takes $O(N^2)$ time. Additionally, measured running times are very small compared to GPs and other alternative surrogates. [1]

## Contents
- ENN surrogate, [`EpistemicNearestNeighbors`](https://github.com/yubo-research/enn/blob/main/src/enn/enn/enn.py) [1]
- TuRBO optimizer via [`create_optimizer`](https://github.com/yubo-research/enn/blob/main/src/enn/turbo/rust_optimizer.py) with config factories
	- `turbo_enn_config()` - TuRBO-ENN (Rust-backed by default)
	- `turbo_zero_config()` - TuRBO-zero (Rust-backed)
	- `lhd_only_config()` - LHD design on every `ask()` (Rust-backed)
	- `turbo_one_config()` - TuRBO with GP surrogate (Python fallback until GP is ported)
The optimizer has an `ask()/tell()` interface. All `turbo_*()` methods follow TuRBO:
  - Generate candidates with RAASP [3] sampling.
  - Select a candidate with Thompson sampling (TuRBO-one), UCB (TuRBO-ENN), or randomly (TURBO-zero).

- Overview of algorithms: [algos.pdf](docs/algos.pdf)



[1] **M. Bafna, Jadhav, S. a., & Sweet, D., (2025).** Taking the GP Out of the Loop. *arXiv preprint arXiv:2506.12818*.
   https://arxiv.org/abs/2506.12818
[2] **Eriksson, D., Pearce, M., Gardner, J. R., Turner, R., & Poloczek, M. (2020).** Scalable Global Optimization via Local Bayesian Optimization. *Advances in Neural Information Processing Systems, 32*.
   https://arxiv.org/abs/1910.01739
[3] **Rashidi, B., Johnstonbaugh, K., & Gao, C. (2024).** Cylindrical Thompson Sampling for High-Dimensional Bayesian Optimization. *Proceedings of The 27th International Conference on Artificial Intelligence and Statistics* (pp. 3502–3510). PMLR.
   https://proceedings.mlr.press/v238/rashidi24a.html


## Installation
`pip install ennbo[with-deps]`
or
`cargo add ennbo`

PyPI wheels are **platform-specific** (they include the `enn.enn_rust` native extension). If `pip install ennbo` gives an import error about `enn.enn_rust`, install a matching wheel (same OS/arch/Python) or build from source (Rust + linkable [Faiss](https://github.com/facebookresearch/faiss) C API; see below).


## Demonstration
[`demo_enn.ipynb`](https://github.com/yubo-research/enn/tree/main/examples/demo_enn.ipynb) - Shows how to use [`EpistemicNearestNeighbors`](https://github.com/yubo-research/enn/blob/main/src/enn/enn/enn.py) to build and query an ENN model.
[`demo_turbo_enn.ipynb`](https://github.com/yubo-research/enn/tree/main/examples/demo_turbo_enn.ipynb) - Shows how to use [`TurboOptimizer`](https://github.com/yubo-research/enn/blob/main/src/enn/turbo/turbo_optimizer.py) to optimize the Ackley function.



## Installation, MacOS

On my MacBook I can run into problems with dependencies and compatibilities.

On MacOS try:
```
micromamba env create -n ennbo -f admin/conda-macos.yml
micromamba activate ennbo
pip install --no-deps ennbo
pytest -sv tests
```

You may replace `micromamba` with `conda` and this will probably still work.

The commands above make sure
- You use the MacOS-specific PyTorch (with `mps`).
- You avoid having multiple, competing OpenMPs installed [PyTorch issue](https://github.com/pytorch/pytorch/issues/44282) [faiss issue](https://github.com/faiss-wheels/faiss-wheels/issues/40).
- You use old enough versions of NumPy and PyTorch to be compatible with faiss [faiss issue](https://github.com/faiss-wheels/faiss-wheels/issues/104).
- Prevent matplotlib's installation from upgrading your NumPy to an incompatible version.
- `ennbo`'s listed dependencies do not undo any of the above (which is fine b/c the above commands set the up correctly).

Run tests with
```
pytest -x -sv tests
```
and they should all pass fairly quickly (~10s-30s).


If your code still crashes or hangs, try this [hack](https://discuss.pytorch.org/t/ran-into-this-issue-while-executing/101460):
```
export KMP_DUPLICATE_LIB_OK=TRUE
export OMP_NUM_THREADS=1
```
I don't recommend this, however, as it will slow things down.

