# danielesavino/unitccl architecture

> Architecture diagram of the GitHub repository danielesavino/unitccl, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/danielesavino/unitccl
- Repository: https://github.com/danielesavino/unitccl

## Overview

unitccl is a Bine-tree NCCL correctness and performance benchmarking toolkit, with a Python CLI for local runs, Slurm sweeps, Nsight profiling, and plotting. The main workflow is CLI request → configured standalone or scaling run → benchmark backend; optional Slurm submission can run sweeps, while profiling and plotting produce analysis outputs. README statements support the native benchmark and test relationships; unsampled CLI subsystems are included by their exact paths, but uncertain internal links are omitted.

Main entry points: [`unitccl_py/src/unitccl_cli/cli.py`](https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/cli.py) (unitccl CLI), [`unitccl_py/src/unitccl_cli/fastest_iface.py`](https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/fastest_iface.py) (Fastest Interface), [`unitccl_py/src/unitccl_cli/slurm_utils.py`](https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/slurm_utils.py) (Slurm Jobs), [`unitccl_py/src/unitccl_cli/nsys_utils.py`](https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/nsys_utils.py) (Nsight Profiling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and Configuration"]
  node_cli["unitccl CLI<br/>[cli.py]"]
  node_config["Configuration<br/>[config.py]"]
  node_build["Build Orchestration<br/>[build_utils.py]"]
  node_logging["CLI Logging<br/>[logging_utils.py]"]
end

subgraph group_runs["Tests and Benchmarks"]
  node_standalone["Correctness Tests"]
  node_scaling["Collective Benchmarks"]
  node_bench["GPU Benchmark<br/>[unitccl_bench.cu]"]
  node_fastest_iface["Fastest Interface<br/>[fastest_iface.py]"]
  node_slurm["Slurm Jobs<br/>[slurm_utils.py]"]
  node_tui["Job Dashboard<br/>[tui_utils.py]"]
end

subgraph group_analysis["Profiling and Analysis"]
  node_nsys["Nsight Profiling<br/>[nsys_utils.py]"]
  node_plotting["Rank Sweep Plots<br/>[plotting.py]"]
  node_schema["Sweep Data Schema<br/>[schema.py]"]
end

subgraph group_native["Native NCCL Layer"]
  node_bine["Bine Graph Generation<br/>[bine_graph.cpp]"]
end

node_user(("Engineer"))
node_fastest["fastest Runner"]
node_mpi["MPI Runtime"]

node_user -->|"invokes"| node_cli
node_cli -->|"reads settings"| node_config
node_cli -->|"runs builds"| node_build
node_cli -->|"runs tests"| node_fastest_iface
node_cli -->|"submits jobs"| node_slurm
node_cli -->|"requests plots"| node_plotting
node_cli -->|"requests profiles"| node_nsys
node_fastest_iface -->|"loads options"| node_config
node_fastest_iface -->|"registers backend"| node_fastest
node_fastest_iface -->|"runs subtests"| node_standalone
node_fastest_iface -->|"compares suites"| node_scaling
node_scaling -->|"spawns via MPI"| node_bench
node_standalone -->|"checks schedules"| node_bine
node_slurm -->|"reads defaults"| node_config
node_slurm -->|"runs sweep"| node_fastest_iface
node_slurm -->|"runs profiles"| node_nsys
node_slurm -.->|"shows job status"| node_tui
node_nsys -.->|"exports analysis"| node_plotting
node_plotting -->|"loads sweep data"| node_schema

click node_cli "https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/cli.py"
click node_config "https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/config.py"
click node_build "https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/build_utils.py"
click node_logging "https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/logging_utils.py"
click node_standalone "https://github.com/danielesavino/unitccl/tree/main/src/standalone"
click node_scaling "https://github.com/danielesavino/unitccl/tree/main/src/scaling"
click node_bench "https://github.com/danielesavino/unitccl/blob/main/src/unitccl_bench.cu"
click node_fastest_iface "https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/fastest_iface.py"
click node_slurm "https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/slurm_utils.py"
click node_tui "https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/tui_utils.py"
click node_nsys "https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/nsys_utils.py"
click node_plotting "https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/plotting.py"
click node_schema "https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/schema.py"
click node_bine "https://github.com/danielesavino/unitccl/blob/main/src/nccl_bridge/bine_graph.cpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_config,node_build,node_logging toneBlue
class node_standalone,node_scaling,node_bench,node_fastest_iface,node_slurm,node_tui toneAmber
class node_nsys,node_plotting,node_schema toneMint
class node_bine toneRose
class node_user,node_fastest,node_mpi toneIndigo
```

## Components

### CLI and Configuration

- [unitccl CLI](https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/cli.py): `unitccl_py/src/unitccl_cli/cli.py`
- [Configuration](https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/config.py): `unitccl_py/src/unitccl_cli/config.py`
- [Build Orchestration](https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/build_utils.py): `unitccl_py/src/unitccl_cli/build_utils.py`
- [CLI Logging](https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/logging_utils.py): `unitccl_py/src/unitccl_cli/logging_utils.py`

### Tests and Benchmarks

- [Correctness Tests](https://github.com/danielesavino/unitccl/tree/main/src/standalone): `src/standalone`
- [Collective Benchmarks](https://github.com/danielesavino/unitccl/tree/main/src/scaling): `src/scaling`
- [GPU Benchmark](https://github.com/danielesavino/unitccl/blob/main/src/unitccl_bench.cu): `src/unitccl_bench.cu`
- [Fastest Interface](https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/fastest_iface.py): `unitccl_py/src/unitccl_cli/fastest_iface.py`
- [Slurm Jobs](https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/slurm_utils.py): `unitccl_py/src/unitccl_cli/slurm_utils.py`
- [Job Dashboard](https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/tui_utils.py): `unitccl_py/src/unitccl_cli/tui_utils.py`

### Profiling and Analysis

- [Nsight Profiling](https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/nsys_utils.py): `unitccl_py/src/unitccl_cli/nsys_utils.py`
- [Rank Sweep Plots](https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/plotting.py): `unitccl_py/src/unitccl_cli/plotting.py`
- [Sweep Data Schema](https://github.com/danielesavino/unitccl/blob/main/unitccl_py/src/unitccl_cli/schema.py): `unitccl_py/src/unitccl_cli/schema.py`

### Native NCCL Layer

- [Bine Graph Generation](https://github.com/danielesavino/unitccl/blob/main/src/nccl_bridge/bine_graph.cpp): `src/nccl_bridge/bine_graph.cpp`

### Other components

- **Engineer**
- **fastest Runner**
- **MPI Runtime**

## Connections

- Engineer → unitccl CLI: invokes (evidence: `README.md`)
- unitccl CLI → Configuration: reads settings (evidence: `unitccl_py/src/unitccl_cli/cli.py`)
- unitccl CLI → Build Orchestration: runs builds (evidence: `unitccl_py/src/unitccl_cli/cli.py`)
- unitccl CLI → Fastest Interface: runs tests (evidence: `unitccl_py/src/unitccl_cli/cli.py`)
- unitccl CLI → Slurm Jobs: submits jobs (evidence: `unitccl_py/src/unitccl_cli/cli.py`)
- unitccl CLI → Rank Sweep Plots: requests plots (evidence: `unitccl_py/src/unitccl_cli/cli.py`)
- unitccl CLI → Nsight Profiling: requests profiles (evidence: `README.md`)
- Fastest Interface → Configuration: loads options (evidence: `unitccl_py/src/unitccl_cli/fastest_iface.py`)
- Fastest Interface → fastest Runner: registers backend (evidence: `unitccl_py/src/unitccl_cli/fastest_iface.py`)
- Fastest Interface → Correctness Tests: runs subtests (evidence: `unitccl_py/src/unitccl_cli/fastest_iface.py`)
- Fastest Interface → Collective Benchmarks: compares suites (evidence: `README.md`)
- Collective Benchmarks → GPU Benchmark: spawns via MPI (evidence: `README.md`)
- Correctness Tests → Bine Graph Generation: checks schedules (evidence: `README.md`)
- Slurm Jobs → Configuration: reads defaults (evidence: `unitccl_py/src/unitccl_cli/slurm_utils.py`)
- Slurm Jobs → Fastest Interface: runs sweep (evidence: `unitccl_py/src/unitccl_cli/slurm_utils.py`)
- Slurm Jobs → Nsight Profiling: runs profiles (evidence: `unitccl_py/src/unitccl_cli/slurm_utils.py`)
- Slurm Jobs → Job Dashboard: shows job status (evidence: `unitccl_py/src/unitccl_cli/slurm_utils.py`)
- Nsight Profiling → Rank Sweep Plots: exports analysis
- Rank Sweep Plots → Sweep Data Schema: loads sweep data (evidence: `unitccl_py/src/unitccl_cli/plotting.py`)