carm-roofline

KO | EN

gitlite — search

#typescript #ai-agents #ai #dsh-plugin #deepseek-harness #open-source #cli #claude-code #codex #developer-tools #react #windows

★ 31 Open GitHub ↗

Cross-platform Cache-Aware Roofline Model (CARM) and Application Benchmarking Tool for Intel, AMD, ARM, and RISC-V CPUs, and NVIDIA and AMD GPUs

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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

## Documentation

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

## Installation

Install from PyPI:

```bash
# 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:

```bash
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:

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

## Requirements

- Python 3.9+
- C compiler (e.g. gcc, clang)
- Optional: [PAPI](https://github.com/icl-utk-edu/papi) headers and binaries for profiling

## Command-Line Interface

The installed command is:

```bash
carm
```

Available subcommands:

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

Show help:

```bash
carm --help
carm benchmark --help
carm gui --help
carm profile --help
```

## Basic Usage

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

```bash
carm benchmark
```

Other usage examples:

```bash
# 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):

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

Use `--name` to label result files:

```bash
carm benchmark --name my_machine
```

## GUI Mode

Launch the dashboard (requires GUI extras):

```bash
carm gui
```

Custom results location and port:

```bash
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.

carm-roofline

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README