Metadata-Version: 2.4
Name: leanhebo
Version: 0.2.0
Summary: A Torch-backed implementation of HEBO's single-objective exact-GP optimizer
Keywords: bayesian-optimization,gaussian-process,hebo,pytorch
Author: LeanHEBO contributors
License-Expression: MIT
License-File: LICENSE
License-File: NOTICE.md
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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-Dist: gpytorch>=1.14
Requires-Dist: numpy>=2.0
Requires-Dist: torch>=2.5
Requires-Dist: pandas>=2.2 ; extra == 'pandas'
Requires-Dist: polars>=1.0 ; extra == 'polars'
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/dimitrismoustakas/LeanHEBO
Project-URL: Repository, https://github.com/dimitrismoustakas/LeanHEBO
Project-URL: Issues, https://github.com/dimitrismoustakas/LeanHEBO/issues
Provides-Extra: pandas
Provides-Extra: polars
Description-Content-Type: text/markdown

# LeanHEBO

LeanHEBO implements the single-objective, exact-GP path of HEBO with Torch-backed numerical
state and compute. It supports bounded floats (linear or logarithmic), integers (linear, stepped,
logarithmic, or powers of a base), Boolean values, and categorical variables, including batched
and contextual suggestions.

This is an independent alpha project, not a new optimization algorithm and not affiliated with
Huawei. See [NOTICE.md](https://github.com/dimitrismoustakas/LeanHEBO/blob/main/NOTICE.md)
for provenance.

## Install

LeanHEBO requires Python 3.11 or newer and is tested on Python 3.11–3.13.

```console
python -m pip install leanhebo
# or
uv add leanhebo
```

Pandas and Polars support is optional:

```console
python -m pip install "leanhebo[pandas,polars]"
```

CPU is the release-tested path. CUDA can be selected with `RuntimeConfig(device="cuda")`, but it
is experimental and is not tested end to end in CI. It never silently falls back from the
configured device.

## Quick start

LeanHEBO minimizes the values passed to `observe`.

```python
import numpy as np

from leanhebo import LeanHEBO
from leanhebo.config import GPConfig, LeanHEBOConfig, RuntimeConfig, SearchConfig
from leanhebo.space import Bool, Categorical, Float, Integer, Space


def loss(row: dict[str, object]) -> float:
    return (
        (float(row["x"]) - 0.3) ** 2
        + (int(row["depth"]) - 6) ** 2 / 25
        + (0.0 if row["activation"] == "gelu" else 0.25)
        + (0.0 if bool(row["use_bias"]) else 0.1)
    )


space = Space(
    Float("x", -2.0, 2.0),
    Integer("depth", 1, 12),
    Categorical("activation", ("relu", "gelu", "silu")),
    Bool("use_bias"),
)
config = LeanHEBOConfig(
    runtime=RuntimeConfig(seed=7),
    gp=GPConfig(initial_steps=15, update_steps=3),
    search=SearchConfig(population_size=32, generations=15),
)
optimizer = LeanHEBO(space, config=config)

for _ in range(3):
    candidates = optimizer.suggest(3)
    optimizer.observe(candidates, np.asarray([loss(row) for row in candidates.to_records()]))

print(optimizer.best_x.to_records()[0], optimizer.best_y)
```

The reduced fitting and search settings keep this example quick; the defaults do more work.

Pass the returned `CandidateBatch` directly to `observe` to avoid re-encoding. Records, NumPy
arrays, Pandas DataFrames, and Polars DataFrames are also accepted at the boundary. Fix contextual
values when suggesting with:

```python
candidates = optimizer.suggest(8, fix_input={"use_bias": True})
```

Non-finite outcomes are dropped by default. Set `nonfinite_policy="raise"` in
`LeanHEBOConfig` to reject them instead.

## Runtime and checkpoints

Numerical observations, transformations, GP state, acquisition evaluation, random streams, and
evolutionary populations use Torch. The exact GP persists across ordinary updates. Both `float32`
and `float64` are supported.

LeanHEBO does not change process-wide Torch or BLAS thread counts on import.

Save and resume without pickling user functions:

```python
optimizer.save("run.leanhebo")
restored = LeanHEBO.load("run.leanhebo", map_location="cpu")
```

The checkpoint restores observations, transformations, model and optimizer state, Sobol progress,
and independent Torch generator states.

## Scope

The `LeanHEBO` optimizer accepts one unconstrained objective and uses an exact Gaussian process,
MACE, and mixed-variable NSGA-II. It does not provide user-facing multi-objective optimization,
random forests, CatBoost, neural ensembles, or sparse GPs.

The supported public API is the top-level optimizer and configuration classes plus the types in
`leanhebo.space` and `leanhebo.data`. Lower-level search, GP, acquisition, transform, and runtime
modules are implementation details.

The repository does not yet claim general speed or optimization-quality superiority. See the
[benchmark README](https://github.com/dimitrismoustakas/LeanHEBO/blob/main/benchmarks/README.md)
for the measurements that exist and the planned Bayesmark comparison.

## Development

See [CONTRIBUTING.md](https://github.com/dimitrismoustakas/LeanHEBO/blob/main/CONTRIBUTING.md)
for setup and checks.
