experiment-queue

Orchestrates batched ML experiments on SSH GPU servers with OOM retry and wave scheduling.

75|7|Updated May 2, 2026
One-click install
npx skills add https://github.com/zjunlp/Mechanist --skill experiment-queue-zjunlp
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: experiment-queue
Source: https://github.com/zjunlp/Mechanist/tree/main/skills/experiment-queue
Command: npx skills add https://github.com/zjunlp/Mechanist --skill experiment-queue-zjunlp

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires pyyaml, and includes scripts (resource) components.

What problem does it solve? Running large batches of ML experiments (multi-seed sweeps, grid searches, teacher-student chains) on remote GPU servers involves tedious manual orchestration: stale screen sessions block new waves, CUDA OOM failures require manual retries, and dependent jobs launch before their prerequisites finish. This Skill automates that entire scheduling layer. ## Core Features & Use Cases - Batch Job Scheduling: Expands declarative grid specs (e.g., N × seeds × dataset sizes) into explicit job manifests and distributes jobs across free GPUs via screen sessions. - OOM-Aware Retry & Stale-Screen Cleanup: Detects CUDA out-of-memory failures from per-job logs, requeues jobs after a configurable delay, and kills screens whose Python process has exited. - Phase Dependencies & Wave Transitions: Enforces depends_on ordering (e.g., train teachers before distilling students) and only launches the next wave after GPU memory settles below threshold. - Crash-Safe State: Writes queue_state.json atomically every poll cycle, so the scheduler can be killed and restarted without losing progress. - Use Case: You need to run 42 distillation experiments (2 model sizes × 4 dataset sizes × 3 seeds, plus teacher pretraining). Describe the grid, and the Skill deploys a detached scheduler on your SSH server that runs all jobs over ~6 hours and produces a summary report. ## Quick Start Ask the agent to queue your multi-seed experiment grid on your SSH GPU server, for example: "Run N in {64,128,256} × seeds {42,200,201} distillation experiments on gpu-server using the experiment queue."

Frequently Asked Questions about experiment-queue

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run multi-seed ML experiments in parallel across GPUs?

Define a grid spec in YAML listing parameter values (seeds, model sizes, dataset sizes) and a command template. The build_manifest.py script expands the Cartesian product into a job manifest, and queue_manager.py schedules jobs onto free GPUs via screen sessions automatically.

How to automatically retry CUDA out of memory failures in batch experiments?

The scheduler scans per-job logs for CUDA OOM patterns, marks the job failed_oom, kills its screen, waits a configurable delay (default 120s), then requeues it on a free GPU. Jobs are marked stuck after exceeding max_attempts (default 3).

When should I use a job queue instead of running experiments one at a time?

Use batch orchestration when you have roughly 10 or more jobs, multi-seed sweeps, or dependent phases like teacher-then-student training. For single ad-hoc runs or fewer than ~5 jobs, a single-run experiment command is simpler and sufficient.

Does the scheduler survive SSH disconnects or crashes?

Yes. The scheduler runs as a detached nohup process on the remote host, so SSH drops do not stop it. It writes queue_state.json atomically every poll cycle, so restarting the scheduler resumes from the recorded state without losing progress.

What are the limitations of this GPU job scheduler?

It assumes single-GPU jobs only, with no mid-run GPU reshuffling, no multi-node distributed queues, and no automatic result syncing back to local. It requires nvidia-smi, screen, and Python 3.8+ on the remote host.