GLOSS: Global-LOcal-unexplored Sampling Strategy

GLOSS is a batch recommendation algorithm for surrogate-based optimization in large, sparsely sampled chemical spaces. It lessens over-reliance on the surrogate model by dividing each recommended batch across three complementary strategies:

• Global: upper-confidence-bound (UCB) acquisition over the whole space, with a diversity radius that keeps the batch from collapsing onto a single predicted optimum.
• Local: harvests the surrogate's multiple local optima directly through a BallTree spatial index.
• Unexplored: distance-gated sampling of regions far from all observed points, where surrogate predictions are unreliable and greedy search stalls.

This repository contains the reference implementation, the test suite, and the complete benchmark used in the accompanying paper.

Installation

From PyPI (library only):

pip install gloss-opt

From source (library plus benchmarks and data):

git clone https://github.com/zbc0315/gloss-opt.git
cd gloss-opt
pip install -e .

Requires Python >= 3.9. Core dependencies: numpy, scipy, scikit-learn. Optional surrogate backends (torch, xgboost, lightgbm) and benchmark extras (pandas, matplotlib, rdkit, openpyxl) install with:

pip install -e ".[full]"

Quickstart

import numpy as np
from gloss import GLOSS

# Discrete candidate pool: 10,000 points in 5 dimensions
rng = np.random.default_rng(0)
candidates = rng.uniform(0.0, 1.0, size=(10_000, 5))

opt = GLOSS(
    space={"candidates": candidates},
    mode="discrete",
    direction="maximize",
    ucb_kappa=2.0,
    diversity_radius=0.02,
    seed=0,
)

# Initial observations
X_obs = candidates[:8]
y_obs = np.sin(X_obs).sum(axis=1)

# One recommendation round: 4 global + 2 local + 2 unexplored points
batch = opt.recommend(
    X_train=X_obs,
    y_train=y_obs,
    strategy_points={"global_best": 4, "local_best": 2, "unexplored": 2, "unconverged": 0},
)

points = np.array([r["point"] for r in batch])   # (8, 5) points to evaluate next

recommend() fits a surrogate on the observations (or accepts a pre-fitted one via surrogate=) and runs the three strategies in sequence with deduplication. It returns a list of dicts, one per recommended point, each carrying the point itself, its predicted_value, and the strategy that proposed it. Continuous spaces are supported via mode="continuous" and space={"bounds": [(lo, hi), ...]}.

Reproducing the paper benchmarks

The benchmark compares GLOSS against four baselines (BO-EI, BO-UCB, GA, and random sampling) on three chemical datasets, with all algorithms sharing one Random Forest surrogate and identical bottom-20% initializations.

# Quick validation (1 seed, 10 rounds)
python -m benchmarks.bench_main --study pilot

# Individual studies
python -m benchmarks.bench_main --study main         # 3 datasets x 5 algorithms
python -m benchmarks.bench_main --study scaling      # QM9 pool 5k -> 100k
python -m benchmarks.bench_main --study complexity   # Arrhenius C1 -> C5
python -m benchmarks.bench_main --study ratio_scaling
python -m benchmarks.bench_main --study ratio_complexity

# Everything (5 seeds; several hours on a single machine)
python -m benchmarks.bench_main --study all

# Local top-K ablation (Supporting Information S2)
python -m benchmarks.bench_local_topk

# Regenerate all paper figures from the result CSVs
python -m benchmarks.plot_benchmark

Result CSVs land in benchmarks/results/ and figures in benchmarks/plots/. The CSVs backing the published figures are included in this repository, so plot_benchmark.py reproduces every figure without re-running the campaigns.

Datasets

No manual download is needed. On first use, benchmarks/datasets.py fetches each dataset from its original public source into benchmarks/data/:

Molecular features (20 RDKit descriptors) are computed locally; the precomputed stratified QM9 pools for the scaling study can be rebuilt with python -m benchmarks.build_qm9_strat.

Tests

pytest tests/ -v

Citing

If you use GLOSS in your work, please cite the paper (see CITATION.cff).

License

MIT. See LICENSE.