carm-roofline 1.0.0.dev1

CARM: Cache-Aware Roofline Model benchmarking and visualization toolkit

CARM Roofline

CARM is a Cache-Aware Roofline Model toolkit for CPU benchmarking and visualization.

The package provides:

• automatic microbenchmark generation for supported ISAs
• arithmetic, memory, and roofline benchmark modes
• CLI output in table, JSON, CSV, and plot formats
• optional web GUI for interactive result visualization

Installation

Install from PyPI:

pip install carm-roofline

Install with optional GUI dependencies:

pip install "carm-roofline[gui]"

Install all extras (GUI + development tools):

pip install "carm-roofline[all]"

Requirements

• Python 3.10+
• Linux (POSIX)
• GCC toolchain (for compiling benchmark binaries)

Command-Line Interface

The installed command is:

carm

Available subcommands:

• benchmark - run benchmark suites
• gui - launch the results dashboard
• profile - reserved (not implemented yet)

Show help:

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

Basic Usage

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

carm benchmark

Quick run (short test time):

carm benchmark --test roofline --test-time 1

Arithmetic-only example:

carm benchmark --test arithmetic --instruction fma --num-ops 32768 --data-type f32

Memory-only example (target L2):

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 under carm_results.

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 CARM 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.