carm-roofline 1.0.2.dev2

CARM: Cache-Aware Roofline Model benchmarking and visualization toolkit

The CARM Tool

Cache-Aware Roofline Model (CARM) toolkit - benchmark, visualize and profile Intel, AMD, ARM, RISC-V CPUs and NVIDIA, AMD GPUs.

The package provides:

• automatic benchmarking for supported ISAs
• arithmetic, memory, and roofline benchmark modes
• optional web GUI for interactive result visualization

[!WARNING] The development branch and associated python package are still experimental, and do not include all features yet. For a stable release, please refer to the main branch.

Documentation

You can find the full documentation at https://champ-hub.github.io/carm-roofline.

Installation

Install from PyPI:

# command-line interface only:
pip install carm-roofline
# with GUI extras:
pip install carm-roofline[gui]
# with all extras (GUI + development tools):
pip install carm-roofline[all]

To avoid conflicts with other packages, we recommend installing in a virtual environment:

python -m venv carm-env
source carm-env/bin/activate
pip install carm-roofline[all]

If cloning the repository directly (e.g. for development or access to example applications), use --recurse-submodules to also fetch the examples:

git clone --recurse-submodules https://github.com/champ-hub/carm-roofline

Requirements

• Python 3.9+
• C compiler (e.g. gcc, clang)
• Optional: PAPI headers and binaries for profiling

Command-Line Interface

The installed command is:

carm

Available subcommands:

• benchmark - run benchmark suites
• gui - launch the results dashboard
• profile - profile an application with PAPI or perf

Show help:

carm --help
carm benchmark --help
carm gui --help
carm profile --help

Basic Usage

Run a default benchmark (roofline mode with auto-detected settings):

carm benchmark

Other usage examples:

# Short roofline benchmark (1 second per micro-bench)
carm benchmark --test roofline --test-time 1
# Arithmetic-only
carm benchmark --test arithmetic --instruction add mul fma --data-type f32
# Memory-only
carm benchmark --test memory --mem-target L2 --ld-st-ratio 2:1
# Dry run (generate benchmark code, skip compile/execute):
carm benchmark --dry-run --test arithmetic --test-time 1 --verbose 4

Output and Results

By default, results are written to the user data directory (via platformdirs). On linux, this is typically ~/.local/share/carm/, on Windows, %APPDATA%\carm\, and on MacOS, ~/Library/Application Support/carm/.

Control output directory and format(s):

carm benchmark --output-dir ./carm_results --output-fmt table json csv plot

Use --name to label result files:

carm benchmark --name my_machine

GUI Mode

Launch the dashboard (requires GUI extras):

carm gui

Custom results location and port:

carm gui --results-dir ./carm_results --gui-port 8050

Publications and Citation

If you use the CARM and the CARM Tool in papers or reports, please cite:

J. Morgado, L. Sousa, A. Ilic. "CARM Tool: Cache-Aware Roofline Model Automatic Benchmarking and Application Analysis", IEEE International Symposium on Workload Characterization (IISWC), Vancouver, British Columbia, Canada, 2024.

A. Ilic, F. Pratas and L. Sousa, "Cache-aware Roofline model: Upgrading the loft," IEEE Computer Architecture Letters, vol. 13, no. 1, pp. 21-24, Jan.-June 2014. doi:10.1109/L-CA.2013.6.

D. Marques, A. Ilic, Z. A. Matveev, and L. Sousa, "Application-driven cache-aware roofline model," Future Generation Computer Systems, vol. 107, pp. 257-273, 2020. doi:10.1016/j.future.2020.01.044.