Skip to content
blackrockPublic

About

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.

Resources

Contributing

Stars

56 stars

Watchers

7 watching

Forks

Repository files navigation

HOLA

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.

Installation

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.txt

This 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.

Quick Start

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.

Going Distributed

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})

Dashboard

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.

Documentation

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

Development

# 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 .

License

Licensed under Apache 2.0.

About

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.

Resources

Contributing

Stars

56 stars

Watchers

7 watching

Forks

Releases

Packages

Used by

Contributors

Languages