Configuration

Configuration

TuneForge is offline by default. All behavior is configurable via environment variables or a .env file in the project root.

Environment variables

Variable	Default	Options	Description
TUNEFORGE_OPTIMIZER	tpe	random, tpe, gp_ei, successive_halving, hyperband	Which optimizer to run
TUNEFORGE_SURFACE	branin	branin, ackley, null	Response surface (objective function)
TUNEFORGE_FIDELITY	correlated	correlated, decorrelated	Fidelity proxy regime
TUNEFORGE_BUDGET	60	any positive integer	Total evaluation budget (full-fidelity equivalent)
TUNEFORGE_SEED	0	any integer	Random seed for reproducibility
TUNEFORGE_BACKEND	numpy	numpy, optuna	Backend (optuna requires pip install ".[optuna]")

.env.example

# TuneForge configuration
# Copy to .env and uncomment lines to override defaults.

# Optimizer to use
# TUNEFORGE_OPTIMIZER=tpe

# Response surface (objective function)
# TUNEFORGE_SURFACE=branin

# Fidelity proxy regime
# TUNEFORGE_FIDELITY=correlated

# Total budget (full-fidelity-equivalent evaluations)
# TUNEFORGE_BUDGET=60

# Random seed
# TUNEFORGE_SEED=0

# Backend: numpy (default, offline) or optuna (cross-check; requires [optuna] extra)
# TUNEFORGE_BACKEND=numpy

CLI overrides

Command-line flags override environment variables:

tuneforge compare --surface ackley --budget 100 --seed 42
tuneforge optimize --optimizer gp_ei --surface branin --fidelity decorrelated

Run tuneforge --help or tuneforge compare --help for the full flag list.

Optional Optuna cross-check

pip install -e ".[optuna]"
TUNEFORGE_BACKEND=optuna tuneforge compare --surface branin --optimizer tpe

This re-runs random and tpe with Optuna's own samplers on the same surfaces, confirming the headline ranking with an independent, battle-tested implementation. The cross-check is never on the default path and is importorskip-ed in tests, so CI stays green without it.

BLAS threading

TuneForge pins BLAS to one thread before numpy imports (tuneforge/__init__.py). This is required because the benchmark runs many small matrix operations and multi-threaded BLAS is both slower and non-deterministic for this workload. Do not remove the pin.

Docker

docker build -t tuneforge .
docker run --rm tuneforge         # runs the offline benchmark
docker run --rm -e TUNEFORGE_SURFACE=ackley tuneforge   # pass env var to Docker