Metadata-Version: 2.5
Name: railmap
Version: 0.1.0
Summary: GPU-NIC-CPU placement and RDMA connection-budget planner for multi-GPU nodes
Project-URL: Homepage, https://github.com/otterbox901/railmap
Project-URL: Documentation, https://github.com/otterbox901/railmap/tree/master/docs
Project-URL: Issues, https://github.com/otterbox901/railmap/issues
Author: Alexander Pershukevich
License-Expression: Apache-2.0
License-File: LICENSE
License-File: railmap/topology/vendor/LICENSE
Keywords: gpu,hpc,infiniband,nccl,numa,nvshmem,rdma,roce,topology
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: System Administrators
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: System :: Clustering
Classifier: Topic :: System :: Distributed Computing
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.10
Requires-Dist: numpy>=1.23
Requires-Dist: nvidia-ml-py>=12
Requires-Dist: rich>=13
Requires-Dist: scipy>=1.13
Requires-Dist: typer>=0.13
Description-Content-Type: text/markdown

# railmap

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/otterbox901/railmap/master/docs/placement-dark.png">
  <img alt="railmap ui, placement view: eight ranks on an ND H100 v5, each GPU linked to the NIC behind the same PCIe switch (PIX), with CPUs from the GPU's NUMA node" src="https://raw.githubusercontent.com/otterbox901/railmap/master/docs/placement-light.png">
</picture>

<sub><code>railmap ui</code> on the ND H100 v5 test fixture (Azure's published topology file and a simulated VM).
More views in <a href="https://github.com/otterbox901/railmap/blob/master/docs/ui.md">docs/ui.md</a>.</sub>

Places each rank of a multi-GPU job on the right NIC, CPU cores and NUMA memory. Also warns when a collective job
will open more RDMA connections per NIC than the NIC handles well.

It targets three gaps in multi-GPU / multi-NIC scaling guidance:

1. **Placement.** Each GPU needs a nearby NIC (PIX/PXB), and cross-socket (SYS) paths hurt. Launchers, containers
   and `CUDA_DEVICE_ORDER` mistakes still put ranks on the wrong NIC or socket. On cloud VMs the guest PCI tree is
   virtualized, so `nvidia-smi topo -m` and sysfs can't show the real layout.
2. **Queue sharding.** No published guidance says how many QPs each GPU should get on a shared NIC, or how to
   spread them across several nearby NICs.
3. **Connection state.** All-to-all RDMA reportedly loses about 59% of a NIC's message rate at about 3,000
   connections, and nothing warns a job before it gets there.

## Quick start

```bash
pip install railmap                         # Python 3.10+, in any venv; or: uv tool install railmap
railmap doctor                              # what this host, container or job step has, and what's missing
railmap plan                                # per-rank GPU, NIC, CPUs, NUMA node
railmap plan --nodes 128                    # ...plus the QP-per-NIC budget for a 128-node all-to-all
torchrun --nproc-per-node 8 --no-python railmap exec -- python train.py   # bind each rank, then exec
railmap ui                                  # the same, as a local web page
```

In a container: `docker run --rm --gpus all --device /dev/infiniband ghcr.io/otterbox901/railmap doctor`. Slurm and
Kubernetes recipes are in [examples/](https://github.com/otterbox901/railmap/tree/master/examples).

## Status

Findings are pending the [Azure ND H100 v5 campaign](https://github.com/otterbox901/railmap/blob/master/docs/measurements.md#azure-campaign).
Until it measures a NIC, the connection budget uses a one-point prior built from the 59% / 3,000 figure.

## Docs

- [Install](https://github.com/otterbox901/railmap/blob/master/docs/install.md): venv, container, Slurm, Kubernetes,
  and what `doctor` checks.
- [Usage](https://github.com/otterbox901/railmap/blob/master/docs/usage.md): every command, topology sources, job
  options, and what `exec` sets.
- [UI](https://github.com/otterbox901/railmap/blob/master/docs/ui.md): the four views of `railmap ui`.
- [Measurements](https://github.com/otterbox901/railmap/blob/master/docs/measurements.md): the probes and the Azure
  campaign.
- [How it works](https://github.com/otterbox901/railmap/blob/master/docs/design.md): path classes, NIC assignment,
  the QP model, and tests.

## License

[Apache-2.0](https://github.com/otterbox901/railmap/blob/master/LICENSE). The bundled Azure topology files are MIT,
from [Azure/azhpc-images](https://github.com/Azure/azhpc-images).
