Hyperparameter Optimization, Lightweight Asynchronous. A Python library for black-box optimization, backed by a Rust engine for speed.
We provide a simple ask/tell interface that works the same way whether the engine runs in your Python process or on a remote server. Define a parameter space, choose an objective, and let HOLA suggest trials.
Pre-built wheels are available for Linux, macOS, and Windows (Python 3.10+).
pip install --require-hashes -r https://raw.githubusercontent.com/blackrock/HOLA/main/install/hola-opt-requirements.txtThis installs the latest published build, currently a release candidate.
The requirements file pins the
version and the SHA-256 digest of every wheel, and resolves hola-opt
from this project's package index only.
hola-opt is not published on PyPI. A project with that name on PyPI
or on any other index is not ours, so install only with the command
above and never add this project's index to an install with
--extra-index-url. The
Getting Started guide explains
why, and covers verifying a download and building from source.
This example minimizes the one-dimensional Forrester function, a standard benchmark with a known minimum of approximately -6.02074 near x = 0.757.
from hola_opt import Study, Space, Real, Minimize
import math
study = Study(
space=Space(x=Real(0.0, 1.0)),
objectives=[Minimize("value")],
strategy="sobol",
seed=42,
)
def forrester(params):
x = params["x"]
term = 6 * x - 2
return {"value": term ** 2 * math.sin(2 * term)}
study.run(forrester, n_trials=50)
best = study.top_k(1)[0]
print(f"Best value: {best.score_vector['value']:.4f}")
print(f"At x = {best.params['x']:.4f}")Space(x=Real(0.0, 1.0)) defines a single continuous parameter.
Minimize("value") tells HOLA to minimize the "value" field
returned by the objective function.
study.run(forrester, n_trials=50) automates 50 ask/tell iterations.
study.top_k(1) returns a one-element list; element [0] is the best
CompletedTrial. Its .score_vector maps each objective group to its
scalarized score (here the single "value" objective), alongside
.params and .metrics.
For multi-machine or language-agnostic deployments, HOLA provides a CLI server and worker. Start a server from a YAML study configuration, then point workers at it.
# Terminal 1: start the server
hola serve config.yaml --port 8000
# Terminal 2: run a worker
hola worker --server http://localhost:8000 --exec "python train.py"The worker sets HOLA_SERVER, HOLA_TRIAL_ID, and HOLA_PARAMS
environment variables, then runs your command. Your script reads its
parameters from HOLA_PARAMS and calls POST /api/tell on the
server to report results. See the CLI guide
for details.
From Python, Study.connect() speaks the same REST protocol without
the CLI.
study = Study.connect("http://localhost:8000")
trial = study.ask()
study.tell(trial.trial_id, {"loss": 0.42})The dashboard/ directory contains a zero-install browser UI for
monitoring live studies or exploring saved checkpoints. Open
dashboard/index.html to explore a checkpoint, or serve it from the
same HOLA server with hola serve config.yaml --dashboard ./dashboard
for live monitoring. It provides convergence plots, Pareto scatter,
parallel coordinates, and a sortable trial table, all updated in real
time via SSE.
| Guide | Description |
|---|---|
| Getting Started | Installation, first optimization, verification |
| Python Guide | Full Python API: spaces, objectives, strategies, Study, Study.connect() |
| CLI & Distributed | YAML config, hola serve, hola worker, multi-machine setup |
| REST API | Endpoint reference with request/response schemas |
| Operations | Secure deployment, probes, metrics, recovery, and shutdown |
| Release Verification | Hosted compatibility, browser/accessibility, scale, recovery, and artifact gates |
| Concepts | Architecture, strategies, scalarization, the unit hypercube |
| Dashboard | Real-time visualization and checkpoint analysis |
# Run all Rust tests
cargo test --locked --workspace --all-features
# Build and test Python bindings
uv sync --directory hola-py --locked --dev --group benchmarks
uv run --directory hola-py maturin develop
uv run --directory hola-py pytest tests/ -v
# Lint
cargo clippy --locked --workspace --all-features -- -D warnings
uv run --directory hola-py ruff check .Licensed under Apache 2.0.