experiment-queue

Experiment Queue

Orchestrate large batches of ML experiments on SSH remote GPU servers with proper state tracking, OOM retry, stale cleanup, and wave transitions.

When to Use This Skill

Use when /run-experiment is insufficient:

• ≥10 jobs that need batching across GPUs
• Multi-seed sweeps (e.g., 21 seeds × 12 cells)
• Wave transitions (run wave 1, wait, run wave 2, wait, run wave 3...)
• Teacher+student chains (train teacher then distill; auto-trigger student after teacher done)
• OOM-prone configs where you need to retry with different GPU or wait
• Mixed seed grids where failed cells need re-running

Do NOT use for:

• Single ad-hoc experiment (use /run-experiment)
• Modal/Vast.ai deployments (those have their own orchestration)
• Experiments that need manual inspection between runs

Why This Exists

Based on session audit (2026-04-16), the major wall-clock sinks in multi-seed grid experiments are:

1. Stale screens — python finishes, wandb uploads, screen hangs, next wave blocked
2. OOM on shared GPU — previous job's memory not yet released
3. Wave race — new wave launches before previous wave fully settles
4. Missing checkpoints — student launches before teacher saved
5. Parser duplication — rewriting multi-seed analysis python every batch

All of these are pure engineering friction that can be orchestrated.

Core Concepts

Job Manifest

A manifest lists jobs with explicit state:

project: my_grid_experiment
cwd: /home/user/your_project
conda: my_env
# Optional: override conda hook path if conda is not at a standard location.
# Can be a bare path (wrapped automatically) or a full `eval "$(... shell.bash hook)"` string.
# Falls back to auto-detect of ~/anaconda3, ~/miniconda3, /opt/anaconda3, etc.,
# or the ARIS_CONDA_HOOK environment variable.
# conda_hook: /custom/path/to/conda
ssh: gpu-server
default_cmd: >
  python run_distill.py --backbone softmax --lam 0.5
  --K 500 --L 96 --W 16 --n_steps 30000 --batch_size 128 --lr 1e-4

preconditions:
  - type: checkpoint_exists
    path: checkpoints/transformer/teacher_L96_K500_N{N}.pt

gpus: [0, 1, 2, 3, 4, 5, 6, 7]
max_parallel: 8
gpu_free_threshold_mib: 500  # optional, default 500; raise for shared servers, lower for tight packing
oom_retry:
  delay: 120
  max_attempts: 3

jobs:
  - id: s200_N64_n50K
    args: {seed: 200, n_hidden: 64, n_train_subset: 50000, subset_seed: 2024}
  - id: s200_N128_n50K
    args: {seed: 200, n_hidden: 128, n_train_subset: 50000, subset_seed: 2024}
  # ... 14 more