🚀 easy_cluster

Useful shell wrappers around common SLURM commands.

   

A small collection of shell wrappers around common SLURM commands, making it easier to see who is using the cluster, how GPUs are allocated, and to manage your own jobs.

All scripts are plain bash and rely on the standard SLURM CLI (squeue, sinfo, scancel, sprio). Run any script with -h (where supported) to see its full usage.

---

🧰 Commands  _{(actively updating)}

	Command	What it does
📋	myjobs	Show your own jobs in the queue.
👥	whoson	Summarise running/pending jobs per user, optionally with GPU and node counts.
📊	gpu-usage	Show aggregate GPU usage across the cluster (or selected nodes).
🖥️	gpu-usage-by-node	Show GPU usage broken down per node.
🟢	free-gpus	List nodes that currently have free GPUs.
🔪	killmyjobs	Cancel your jobs, with options to filter and exclude.

💡 Click a command below to unfold its arguments. Recommend to use these commands with watch <cmd> live monitoring: e.g. watch myjobs --start.

📋  myjobs  — Shows your own jobs in the queue (a thin wrapper around squeue -u $USER).

Arguments

Any arguments are passed straight through to squeue, so every squeue option works. Some handy ones:

• --start — show the estimated start time for your pending jobs.
• -t <state> — filter by job state, e.g. -t RUNNING or -t PENDING.
• -i <seconds> — refresh the listing every N seconds (live view).

👥  whoson  — Lists every user with queued or running jobs, showing a running/pending/total breakdown of their job count.

Arguments

• -g — additionally report, per user, the number of nodes and GPUs used (each as running/pending/total).

GPU counts are read from the job's TRES (gres/gpu=N), so they reflect the total GPUs requested/allocated for each job regardless of how they were requested (--gpus, --gpus-per-node, --gpus-per-task, --gres).

📊  gpu-usage  — Prints aggregate GPU usage as in_use, usable, total, and free counts.

Arguments

• -n <nodelist> — restrict to specific nodes; accepts a comma-separated list (charles01,charles03) or SLURM's summarised form (charles[01-06,11-19]).
• -p — output raw CSV instead of the pretty table (the table is the default).
• -h — suppress the header row (only applies together with -p).

The number of free GPUs is usable - in_use.

🖥️  gpu-usage-by-node  — Same GPU breakdown as gpu-usage, but with one row per node (prefixed with a timestamp and node name).

Arguments

• -n <nodelist> — restrict to specific nodes (same format as gpu-usage).
• -p — output raw CSV instead of the pretty table (the table is the default).
• -H / -h — force the header on / off (apply when using -p).

🟢  free-gpus  — Lists each node that currently has at least one free GPU, with how many GPUs are free on it.

Takes no arguments. If every usable GPU is currently allocated, it instead tells you the cluster is full and prints the current priority queue (sprio -l).

🔪  killmyjobs  — Cancels your jobs; by default cancels both running and queued jobs.

Arguments

• -g — only cancel running jobs, leaving queued jobs in place.
• -n <nodelist> — only cancel jobs on the given nodes (same format as gpu-usage).
• -e <JOBID> — exclude a job from being cancelled; may be given multiple times.

---

📦 Installation

Open a terminal, and cd to <PATH-ON-YOUR-CLUSTER> then:

git clone https://github.com/NanboLi/easy_cluster.git
echo 'export PATH=<PATH-ON-YOUR-CLUSTER>/easy_cluster:$PATH' >> ~/.bashrc
source ~/.bashrc

You are ready to go! 🎉