Hyperparameter Sweep

Create a sweep, claim trials across parallel workers, and find the best hyperparameters.

Grid search with transactional trial claiming
Random search with log-uniform scaling
Parallel workers on multiple machines

Time to complete: ~10 minutes

Prerequisites

pip install sagea-cursus
CURSUS_API_KEY and CURSUS_BASE_URL set in your environment
A Cursus server instance (hosted or self-hosted)

Step 1: Create a sweep

# sweep.py
import sagea_cursus as cursus
 
sweep = cursus.create_sweep(
    "my-experiment",
    {
        "lr": {"min": 1e-5, "max": 1e-1, "scale": "log"},
        "batch_size": {"values": [16, 32, 64]},
    },
    name="lr-batch-search",
)
print("sweep ID:", sweep["id"])

Step 2: Write the worker loop

Each worker claims trials and trains until the sweep is exhausted:

# worker.py
import sagea_cursus as cursus
 
while (trial := cursus.next_trial(sweep_id)) is not None:
    run = cursus.init(
        project="my-experiment",
        config=trial["config"],
        name=f"sweep-{trial['trial']}",
        sweep_id=trial["sweep_id"],
    )
    try:
        # train with trial["config"]["lr"], trial["config"]["batch_size"]
        train(trial["config"])
        cursus.finish()
    except Exception:
        cursus.finish("crashed")
        raise

Step 3: Run parallel workers

Launch one worker per machine:

# machine 1
python worker.py
 
# machine 2
python worker.py

Grid trials are claimed transactionally — concurrent workers never share a cell. next_trial() returns None when the grid is exhausted or the sweep is finished/cancelled.

Step 4: Review results

Open the sweep page on the dashboard to see all trials with their configs and final metrics. Compare results to find the best hyperparameter combination.