Metadata-Version: 2.4
Name: carm-roofline
Version: 1.0.0.dev1
Summary: CARM: Cache-Aware Roofline Model benchmarking and visualization toolkit
Author: CHaMP Team
License: MIT
Project-URL: Homepage, https://github.com/champ-hub/carm-roofline
Project-URL: Repository, https://github.com/champ-hub/carm-roofline
Project-URL: Issues, https://github.com/champ-hub/carm-roofline/issues
Keywords: benchmark,roofline,performance,hpc,cache,simd
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Benchmark
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: rich>=14.3.2
Requires-Dist: rich-argparse>=1.7.0
Requires-Dist: numpy>=2.2.6
Requires-Dist: matplotlib>=3.7.2
Requires-Dist: tomli>=2.0.0
Provides-Extra: gui
Requires-Dist: dash; extra == "gui"
Requires-Dist: dash-bootstrap-components; extra == "gui"
Requires-Dist: dash-daq; extra == "gui"
Requires-Dist: diskcache; extra == "gui"
Requires-Dist: plotly; extra == "gui"
Requires-Dist: pandas; extra == "gui"
Provides-Extra: dev
Requires-Dist: pytest>=9.0.2; extra == "dev"
Requires-Dist: ruff>=0.14.14; extra == "dev"
Requires-Dist: pre-commit>=4.5.1; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Provides-Extra: analysis
Provides-Extra: all
Requires-Dist: carm-roofline[dev,gui]; extra == "all"


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

```bash
pip install carm-roofline
```

Install with optional GUI dependencies:

```bash
pip install "carm-roofline[gui]"
```

Install all extras (GUI + development tools):

```bash
pip install "carm-roofline[all]"
```

## Requirements

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

## Command-Line Interface

The installed command is:

```bash
carm
```

Available subcommands:

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

Show help:

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

## Basic Usage

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

```bash
carm benchmark
```

Quick run (short test time):

```bash
carm benchmark --test roofline --test-time 1
```

Arithmetic-only example:

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

Memory-only example (target L2):

```bash
carm benchmark --test memory --mem-target L2 --ld-st-ratio 2:1
```

Dry run (generate benchmark code, skip compile/execute):

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

```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 CARM in papers or reports, please cite:

<p>
  <a href="https://doi.org/10.1109/L-CA.2013.6" alt="Publication">
    <img src="https://img.shields.io/badge/DOI-10.1109/L--CA.2013.6-blue.svg"/></a>
</p>

<p>
  <a href="https://doi.org/10.1016/j.future.2020.01.044" alt="Publication">
    <img src="https://img.shields.io/badge/DOI-10.1016/j.future.2020.01.044-blue.svg"/></a>
</p>

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.
