# p4tare/parallel-reduction-benchmark architecture

> Architecture diagram of the GitHub repository p4tare/parallel-reduction-benchmark, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/p4tare/parallel-reduction-benchmark
- Repository: https://github.com/p4tare/parallel-reduction-benchmark

## Overview

Parallel Reduction Benchmark is a research framework for comparing reduction performance and energy use across CPU, NVIDIA GPU, multi-GPU, and heterogeneous systems. Users configure and plan campaigns, then run randomized experiment blocks: Python prepares datasets and topology-aware tasks, coordinates a native worker through its measurement protocol, validates results, and writes raw and summarized outputs. The native worker executes CPU/GPU strategies and reports timing metrics. The README documents energy metering and diagnostic capabilities; sampled excerpts do not show every runtime call, so some documented subsystem links use README evidence.

Main entry points: [`prbench/cli.py`](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/cli.py) (Command interface), [`prbench/runner.py`](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/runner.py) (Experiment runner), [`native/src/main.cpp`](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/main.cpp) (Native worker entry), [`native/src/strategy.cpp`](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/strategy.cpp) (Reduction strategies)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Python orchestration"]
  node_cli["Command interface<br/>[cli.py]"]
  node_configuration["Configuration<br/>[config.py]"]
  node_experiment_runner["Experiment runner<br/>[runner.py]"]
  node_worker_protocol["Worker protocol<br/>[protocol.py]"]
end

subgraph group_experiment["Experiment design"]
  node_algorithm_catalog["Algorithm catalog<br/>[catalog.py]"]
  node_campaign_planner["Sweep planner<br/>[sweep.py]"]
  node_topology["Hardware topology<br/>[topology.py]"]
  node_capacity["Capacity checks<br/>[capacity.py]"]
  node_dataset_factory["Dataset generation<br/>[datasets.py]"]
end

subgraph group_measurement["Measurement and results"]
  node_manifest["Run manifest<br/>[manifest.py]"]
  node_validation["Result validation<br/>[validation.py]"]
  node_energy_meters["Energy metering<br/>[energy.py]"]
  node_telemetry["Hardware telemetry<br/>[telemetry.py]"]
  node_result_store[("Raw and summary results<br/>[results.py]")]
end

subgraph group_worker["Native reduction worker"]
  node_native_worker["Native worker entry<br/>[main.cpp]"]
  node_worker_config["Worker arguments<br/>[cli.cpp]"]
  node_strategy_engine["Reduction strategies<br/>[strategy.cpp]"]
  node_cpu_backend["CPU reduction<br/>[cpu_backend.cpp]"]
  node_gpu_backend["GPU reduction<br/>[gpu_backend.cu]"]
  node_integrated_strategy["Hybrid strategy"]
  node_native_dataset["Resident dataset<br/>[dataset.cpp]"]
end

node_researcher(("Researcher"))
node_rapl["RAPL counters"]
node_nvml["NVML telemetry"]

node_researcher -->|"invokes"| node_cli
node_cli -->|"loads"| node_configuration
node_cli -->|"plans tasks"| node_campaign_planner
node_campaign_planner -->|"resolves algorithms"| node_algorithm_catalog
node_campaign_planner -->|"assigns resources"| node_topology
node_cli -->|"discovers hardware"| node_topology
node_cli -->|"checks capacity"| node_capacity
node_cli -->|"prepares datasets"| node_dataset_factory
node_cli -->|"writes manifest"| node_manifest
node_cli -->|"runs campaign"| node_experiment_runner
node_experiment_runner -->|"exchanges events"| node_worker_protocol
node_experiment_runner -->|"gets datasets"| node_dataset_factory
node_experiment_runner -->|"validates outputs"| node_validation
node_experiment_runner -->|"measures energy"| node_energy_meters
node_experiment_runner -->|"collects telemetry"| node_telemetry
node_experiment_runner -->|"appends samples"| node_result_store
node_energy_meters -->|"reads counters"| node_rapl
node_telemetry -->|"queries devices"| node_nvml
node_experiment_runner -->|"launches worker"| node_native_worker
node_native_worker -->|"parses arguments"| node_worker_config
node_native_worker -->|"creates strategy"| node_strategy_engine
node_strategy_engine -->|"dispatches CPU work"| node_cpu_backend
node_strategy_engine -->|"dispatches GPU work"| node_gpu_backend
node_strategy_engine -.->|"selects hybrid execution"| node_integrated_strategy
node_native_worker -->|"loads dataset"| node_native_dataset

click node_cli "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/cli.py"
click node_configuration "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/config.py"
click node_algorithm_catalog "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/catalog.py"
click node_campaign_planner "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/sweep.py"
click node_topology "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/topology.py"
click node_capacity "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/capacity.py"
click node_dataset_factory "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/datasets.py"
click node_manifest "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/manifest.py"
click node_experiment_runner "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/runner.py"
click node_worker_protocol "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/protocol.py"
click node_validation "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/validation.py"
click node_energy_meters "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/energy.py"
click node_telemetry "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/telemetry.py"
click node_result_store "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/results.py"
click node_native_worker "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/main.cpp"
click node_worker_config "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/cli.cpp"
click node_strategy_engine "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/strategy.cpp"
click node_cpu_backend "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/cpu_backend.cpp"
click node_gpu_backend "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/gpu_backend.cu"
click node_integrated_strategy "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/integrated_strategy.cu"
click node_native_dataset "https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/dataset.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_configuration,node_experiment_runner,node_worker_protocol toneBlue
class node_algorithm_catalog,node_campaign_planner,node_topology,node_capacity,node_dataset_factory toneAmber
class node_manifest,node_validation,node_energy_meters,node_telemetry,node_result_store toneMint
class node_native_worker,node_worker_config,node_strategy_engine,node_cpu_backend,node_gpu_backend,node_integrated_strategy,node_native_dataset toneRose
class node_researcher,node_rapl,node_nvml toneIndigo
```

## Components

### Python orchestration

- [Command interface](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/cli.py): `prbench/cli.py`
- [Configuration](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/config.py): `prbench/config.py`
- [Experiment runner](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/runner.py): `prbench/runner.py`
- [Worker protocol](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/protocol.py): `prbench/protocol.py`

### Experiment design

- [Algorithm catalog](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/catalog.py): `prbench/catalog.py`
- [Sweep planner](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/sweep.py): `prbench/sweep.py`
- [Hardware topology](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/topology.py): `prbench/topology.py`
- [Capacity checks](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/capacity.py): `prbench/capacity.py`
- [Dataset generation](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/datasets.py): `prbench/datasets.py`

### Measurement and results

- [Run manifest](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/manifest.py): `prbench/manifest.py`
- [Result validation](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/validation.py): `prbench/validation.py`
- [Energy metering](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/energy.py): `prbench/energy.py`
- [Hardware telemetry](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/telemetry.py): `prbench/telemetry.py`
- [Raw and summary results](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/prbench/results.py): `prbench/results.py`

### Native reduction worker

- [Native worker entry](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/main.cpp): `native/src/main.cpp`
- [Worker arguments](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/cli.cpp): `native/src/cli.cpp`
- [Reduction strategies](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/strategy.cpp): `native/src/strategy.cpp`
- [CPU reduction](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/cpu_backend.cpp): `native/src/cpu_backend.cpp`
- [GPU reduction](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/gpu_backend.cu): `native/src/gpu_backend.cu`
- [Hybrid strategy](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/integrated_strategy.cu): `native/src/integrated_strategy.cu`
- [Resident dataset](https://github.com/p4tare/parallel-reduction-benchmark/blob/main/native/src/dataset.cpp): `native/src/dataset.cpp`

### Other components

- **Researcher**
- **RAPL counters**
- **NVML telemetry**

## Connections

- Researcher → Command interface: invokes (evidence: `README.md`)
- Command interface → Configuration: loads (evidence: `prbench/cli.py`)
- Command interface → Sweep planner: plans tasks (evidence: `prbench/cli.py`)
- Sweep planner → Algorithm catalog: resolves algorithms (evidence: `prbench/sweep.py`)
- Sweep planner → Hardware topology: assigns resources (evidence: `prbench/sweep.py`)
- Command interface → Hardware topology: discovers hardware (evidence: `README.md`)
- Command interface → Capacity checks: checks capacity (evidence: `prbench/cli.py`)
- Command interface → Dataset generation: prepares datasets (evidence: `prbench/cli.py`)
- Command interface → Run manifest: writes manifest (evidence: `prbench/cli.py`)
- Command interface → Experiment runner: runs campaign (evidence: `prbench/cli.py`)
- Experiment runner → Worker protocol: exchanges events (evidence: `prbench/runner.py`)
- Experiment runner → Dataset generation: gets datasets (evidence: `prbench/runner.py`)
- Experiment runner → Result validation: validates outputs (evidence: `prbench/runner.py`)
- Experiment runner → Energy metering: measures energy (evidence: `prbench/runner.py`)
- Experiment runner → Hardware telemetry: collects telemetry (evidence: `prbench/runner.py`)
- Experiment runner → Raw and summary results: appends samples (evidence: `prbench/runner.py`)
- Energy metering → RAPL counters: reads counters (evidence: `README.md`)
- Hardware telemetry → NVML telemetry: queries devices (evidence: `README.md`)
- Experiment runner → Native worker entry: launches worker (evidence: `README.md`)
- Native worker entry → Worker arguments: parses arguments (evidence: `native/src/main.cpp`)
- Native worker entry → Reduction strategies: creates strategy (evidence: `native/src/main.cpp`)
- Reduction strategies → CPU reduction: dispatches CPU work (evidence: `native/src/strategy.cpp`)
- Reduction strategies → GPU reduction: dispatches GPU work (evidence: `native/src/strategy.cpp`)
- Reduction strategies → Hybrid strategy: selects hybrid execution
- Native worker entry → Resident dataset: loads dataset (evidence: `native/src/main.cpp`)
