CUBench

The Definitive Open-Source GPU Benchmarking Utility

A comprehensive CUDA-based tool for evaluating GPU performance across a variety of kernel configurations, memory access patterns and occupancy scenarios.

Features

• Measures execution time over multiple trials for statistical significance
• Tests a range of thread block sizes and grid configurations
• Reports per-kernel occupancy and register utilisation
• Customisable benchmark parameters via BenchmarkConfig
• Outputs human-readable summaries to the console

Requirements

• CUDA Toolkit (version 11.0 or later)
• NVCC compiler
• C++17-compatible standard library
• 1 or more CUDA-capable GPUs

Building

1. Ensure the CUDA environment variables are set (e.g. CUDA_HOME).

2. Compile with provided makefile:

make

Usage

Run the benchmark executable. By default, it uses device 0 and the settings in BenchmarkConfig:

./cubench

Sample output:

=== Rasterisation Benchmark ===
Triangles: 10000
Resolution: 1920x1080
Time: 158.24 ms (6.32 FPS)
Triangles/sec: 0.06 M
Pixels/sec: 13.10 M

Command-line options

Flag	Description
--json	Write results to a JSON file instead of the column layout
--json-file <path>	JSON output path (default cubench_results.json; implies --json)
--headless	No interactive prompts; exit after writing the JSON file (requires --json)
--only <names>	Run only benchmarks matching the comma-separated, case-insensitive name patterns (substring match), e.g. --only memory,tensor
--list	Print all benchmark names (in run order) and exit
--help, -h	Show usage

The exit code is non-zero when the run fails (no CUDA device, JSON file could not be written, --only matched nothing), so scripts and CI can detect failures. The JSON file is written atomically (temp file + rename) — watchers of the output path never see a partial document.

JSON values that look like <number> [unit] (e.g. 123.45 GB/s) are emitted with the numeric part and unit as separate fields alongside the raw string, so consumers don't need to re-parse strings.

Progress bar

A live progress bar is drawn on stderr while benchmarks run (with sixel graphics where the terminal supports it — force on/off with CUBENCH_SIXEL=1/0). Per-benchmark durations are cached between runs (~/.cache/cubench_timings.tsv on Linux, %LOCALAPPDATA%\cubench_timings.tsv on Windows, override with CUBENCH_TIMINGS_FILE), which lets the bar show a per-task ETA that accounts for how wildly benchmark durations differ. On the first run (no cache yet) each benchmark is estimated from a built-in rough relative-duration weight, so long benchmarks like the thermal and power tests are predicted long instead of being assumed average; subsequent runs use the cached real timings.

(can you tell i'm proud of this yet?)

Custom Configuration

Modify the BenchmarkConfig struct in main.cu to tweak:

• Number of trials per test
• Input sizes for occupancy and memory benchmarks
• Minimum and maximum block sizes

Recompile after changes.

Notes

I have a lot of other projects i need to create and maintain. expect delayed bugfixes / features / responses.

Licence

This project is licensed under the Apache License 2.0. See LICENSE for details.

Author

Stevenson Parker

Created: 24 July 2025