ennbo 0.1.4

Epistemic Nearest Neighbors

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 model, EpistemicNearestNeighbors [1]
• TuRBO-ENN optimizer, class TurboOptimizer has four modes
  • TURBO_ONE - A clone of the TuRBO [2] reference code, reworked to have an ask()/tell() interface.
  • TURBO_ENN - Same as TURBO_ONE, except uses ENN instead of GP and Pareto(mu, se) instead of Thompson sampling.
  • TURBO_ZERO - Same as TURBO_ONE, except randomly-chosen RAASP [3] candidates are picked to be proposals. There is no surrogate.
  • LHD_ONLY - Just creates an LHD design for every ask(). Good for a baseline and for testing.

[1] Sweet, D., & Jadhav, S. A. (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

Installation (conda)

End-user install (after you upload to a channel, or after conda-forge picks it up):

conda install -c conda-forge -c <YOUR_CHANNEL> ennbo

Note: this only works if all runtime deps are available on conda channels. If a dependency is only on PyPI, you’ll need to also package it for conda (your own channel or conda-forge) first.

Local build + upload to anaconda.org:

conda install -c conda-forge conda-build anaconda-client
conda build conda/recipe
anaconda upload <PATH_TO_CONDA_BLD>/noarch/ennbo-*.tar.bz2

Demonstration

demo_enn.ipynb - Shows how to use EpistemicNearestNeighbors to build and query an ENN model. demo_turbo_enn.ipynb - Shows how to use TurboOptimizer 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 faiss issue.
• You use old enough versions of NumPy and PyTorch to be compatible with faiss faiss issue.
• 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 your, try this hack:

export KMP_DUPLICATE_LIB_OK=TRUE
export OMP_NUM_THREADS=1

I don't recommend this, however, as it will slow things down.