# danielesavino/collbench architecture

> Architecture diagram of the GitHub repository danielesavino/collbench, 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/collbench
- Repository: https://github.com/danielesavino/collbench

## Overview

CollBench instruments MPI point-to-point operations inside user-defined collectives, records per-operation timing, gathers rank-local records at the root, and exports JSON for visualization. The graph also preserves the documented profiling toggle and both visualization tools. Source excerpts establish the list, gather, and export implementation; some wiring is documented in the README rather than shown in sampled implementation files.

Main entry points: [`src/dist_list.c`](https://github.com/danielesavino/collbench/blob/main/src/dist_list.c) (Record list and gather), [`include/CollBench/init.h`](https://github.com/danielesavino/collbench/blob/main/include/CollBench/init.h) (Scope and macros), [`src/export.c`](https://github.com/danielesavino/collbench/blob/main/src/export.c) (JSON export), [`scripts/tree.py`](https://github.com/danielesavino/collbench/blob/main/scripts/tree.py) (Tree visualizer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Profiling API"]
  node_scope_api["Scope and macros<br/>[init.h]"]
  node_operation_api["Operation records<br/>[bench.h]"]
  node_point_to_point["Profiled MPI calls<br/>[dist_list.h]"]
end

subgraph group_runtime["Recording Runtime"]
  node_list_runtime["Record list and gather<br/>[dist_list.c]"]
  node_timing_runtime["Timing and MPI datatype<br/>[bench.c]"]
  node_json_export["JSON export<br/>[export.c]"]
  node_error_support["Error handling<br/>[errors.h]"]
end

subgraph group_analysis["Visualization"]
  node_tree_viz["Tree visualizer<br/>[tree.py]"]
  node_butterfly_viz["Collective visualizer<br/>[butterfly.py]"]
end

node_mpi_user(("MPI application"))
node_json_data["Profiling JSON"]
node_analyst(("Analyst"))
node_visual_output["Plots"]

node_mpi_user -->|"opens profiling scope"| node_scope_api
node_mpi_user -->|"instruments MPI calls"| node_point_to_point
node_scope_api -->|"initializes datatype"| node_timing_runtime
node_scope_api -->|"allocates and gathers"| node_list_runtime
node_scope_api -->|"exports gathered records"| node_json_export
node_point_to_point -->|"records operations"| node_list_runtime
node_list_runtime -->|"initializes records"| node_timing_runtime
node_list_runtime -->|"checks errors"| node_error_support
node_json_export -->|"reads gathered records"| node_list_runtime
node_json_export -->|"formats operation data"| node_timing_runtime
node_json_export -->|"writes JSON"| node_json_data
node_analyst -->|"visualizes tree data"| node_tree_viz
node_analyst -->|"visualizes collective data"| node_butterfly_viz
node_json_data -->|"reads JSON"| node_tree_viz
node_json_data -->|"reads JSON"| node_butterfly_viz
node_tree_viz -->|"renders plot"| node_visual_output
node_butterfly_viz -->|"renders plot"| node_visual_output

click node_scope_api "https://github.com/danielesavino/collbench/blob/main/include/CollBench/init.h"
click node_operation_api "https://github.com/danielesavino/collbench/blob/main/include/CollBench/bench.h"
click node_point_to_point "https://github.com/danielesavino/collbench/blob/main/include/CollBench/dist_list.h"
click node_list_runtime "https://github.com/danielesavino/collbench/blob/main/src/dist_list.c"
click node_timing_runtime "https://github.com/danielesavino/collbench/blob/main/src/bench.c"
click node_json_export "https://github.com/danielesavino/collbench/blob/main/src/export.c"
click node_error_support "https://github.com/danielesavino/collbench/blob/main/include/CollBench/errors.h"
click node_tree_viz "https://github.com/danielesavino/collbench/blob/main/scripts/tree.py"
click node_butterfly_viz "https://github.com/danielesavino/collbench/blob/main/scripts/butterfly.py"

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_scope_api,node_operation_api,node_point_to_point toneBlue
class node_list_runtime,node_timing_runtime,node_json_export,node_error_support toneAmber
class node_tree_viz,node_butterfly_viz toneMint
class node_mpi_user,node_json_data,node_analyst,node_visual_output toneIndigo
```

## Components

### Profiling API

- [Scope and macros](https://github.com/danielesavino/collbench/blob/main/include/CollBench/init.h): `include/CollBench/init.h`
- [Operation records](https://github.com/danielesavino/collbench/blob/main/include/CollBench/bench.h): `include/CollBench/bench.h`
- [Profiled MPI calls](https://github.com/danielesavino/collbench/blob/main/include/CollBench/dist_list.h): `include/CollBench/dist_list.h`

### Recording Runtime

- [Record list and gather](https://github.com/danielesavino/collbench/blob/main/src/dist_list.c): `src/dist_list.c`
- [Timing and MPI datatype](https://github.com/danielesavino/collbench/blob/main/src/bench.c): `src/bench.c`
- [JSON export](https://github.com/danielesavino/collbench/blob/main/src/export.c): `src/export.c`
- [Error handling](https://github.com/danielesavino/collbench/blob/main/include/CollBench/errors.h): `include/CollBench/errors.h`

### Visualization

- [Tree visualizer](https://github.com/danielesavino/collbench/blob/main/scripts/tree.py): `scripts/tree.py`
- [Collective visualizer](https://github.com/danielesavino/collbench/blob/main/scripts/butterfly.py): `scripts/butterfly.py`

### Other components

- **MPI application**
- **Profiling JSON**
- **Analyst**
- **Plots**

## Connections

- MPI application → Scope and macros: opens profiling scope (evidence: `README.MD`)
- MPI application → Profiled MPI calls: instruments MPI calls (evidence: `README.MD`)
- Scope and macros → Timing and MPI datatype: initializes datatype (evidence: `README.MD`)
- Scope and macros → Record list and gather: allocates and gathers (evidence: `include/CollBench/init.h`)
- Scope and macros → JSON export: exports gathered records (evidence: `include/CollBench/init.h`)
- Profiled MPI calls → Record list and gather: records operations (evidence: `include/CollBench/dist_list.h`)
- Record list and gather → Timing and MPI datatype: initializes records (evidence: `src/dist_list.c`)
- Record list and gather → Error handling: checks errors (evidence: `src/dist_list.c`)
- JSON export → Record list and gather: reads gathered records (evidence: `src/export.c`)
- JSON export → Timing and MPI datatype: formats operation data (evidence: `src/export.c`)
- JSON export → Profiling JSON: writes JSON (evidence: `src/export.c`)
- Analyst → Tree visualizer: visualizes tree data (evidence: `scripts/tree.py`)
- Analyst → Collective visualizer: visualizes collective data (evidence: `scripts/butterfly.py`)
- Profiling JSON → Tree visualizer: reads JSON (evidence: `scripts/tree.py`)
- Profiling JSON → Collective visualizer: reads JSON (evidence: `scripts/butterfly.py`)
- Tree visualizer → Plots: renders plot (evidence: `scripts/tree.py`)
- Collective visualizer → Plots: renders plot (evidence: `scripts/butterfly.py`)