Metadata-Version: 2.4
Name: slmtop
Version: 0.1.0
Summary: Clear Slurm resource views for nodes, GPUs, memory, CPUs, and queued jobs.
Author: Wei Hongxin
License: MIT
Project-URL: Homepage, https://github.com/ml-stat-Sustech/slmtop
Project-URL: Issues, https://github.com/ml-stat-Sustech/slmtop/issues
Keywords: slurm,hpc,gpu,cluster,scheduler
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Clustering
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# slmtop

`slmtop` is a small Python CLI for day-to-day Slurm resource inspection.
It focuses on the views people usually need before submitting or debugging jobs:

- nvitop-like top view: node resources above current job requests
- free GPU model/count per node
- current queue resource requests, including GPU, CPU, memory, nodes, and time limit
- node GPU and CPU allocation/free capacity

It uses Slurm's own commands (`scontrol`, `squeue`, `sinfo`) and has no runtime
Python dependencies.

## Install

From PyPI:

```bash
python3 -m pip install slmtop
```

From this directory:

```bash
python3 -m pip install .
```

For editable development:

```bash
python3 -m pip install -e .
```

## Usage

Show node resources above current job requests:

```bash
slmtop
```

The output is split into a compact resource dashboard and a job table:

```text
slmtop  nodes 2  |  gpu free 9/16  |  cpu free 144/256

NODE    PARTITION  GPU_USE               CPU_FREE  CPU_USE           STATE
------  ---------  --------------------  --------  ----------------  -----
gpu001  gpu        [########..] 6/8 75%  32/128    [########..] 75%  MIXED
gpu002  gpu        [#.........] 1/8 12%  112/128   [#.........] 12%  IDLE

------------------------------------------------------------------------

JOBID  USER   STATE    GPU  MEM   CPU  NODE    PARTITION  TIME  NAME
-----  -----  -------  ---  ----  ---  ------  ---------  ----  -----
123    alice  RUNNING  4    128G  32   gpu001  gpu        2:31  train
```

Only show nodes with at least one free GPU in the top section:

```bash
slmtop --free
```

## Notes

Slurm clusters differ in how precisely they report allocated GPU types. If a
node has multiple GPU models but `AllocTRES` only says `gres/gpu=2`, Slurm does
not expose which model is allocated in that field. In that case `slmtop`
prints `?` for typed free GPU counts and adds a note.
