1# benchcompress
3A benchmarking framework for evaluating compression algorithms on scientific data arrays.
5Latest benchmark results: https://magland.github.io/benchcompress/
7Paper (WIP): https://magland.github.io/benchcompress/paper
9## Overview
11Benchcompress is a comprehensive benchmarking framework for evaluating compression algorithms on scientific data arrays. The system follows an automated workflow:
131. **Defining Components**
14 - Algorithms are implemented in `benchcompress/src/benchcompress/algorithms/`
15 - Datasets are defined in `benchcompress/src/benchcompress/datasets/`
16 - Each component specifies metadata like version, tags, and compatibility requirements
182. **Automated Benchmarking**
19 - Benchmarks run automatically via GitHub Actions on pushes to main branch
20 - For each compatible algorithm-dataset pair, measures:
21 - Compression ratio
22 - Encoding throughput (MB/s)
23 - Decoding throughput (MB/s)
24 - Results are verified by decompressing and comparing with original data
263. **Result Storage**
27 - Results are committed to a dedicated `benchmark-results` branch
28 - Local and remote caching system prevents redundant rerunning of benchmarks (only modified or added components are re-benchmarked)
29 - Caching is based on algorithm and dataset versions
314. **Web Interface**
32 - Interactive visualization at https://magland.github.io/benchcompress/
33 - Filter and sort results by dataset or algorithm
34 - Visual charts for comparing performance metrics
35 - Export results to CSV for further analysis
37## For developers
39The project consists of two main components:
41- `benchcompress/`: Python package containing the core benchmarking framework, algorithms, and datasets
42- `web-ui/`: React-based web interface for visualizing benchmark results
44### Local Development Setup
461. Install Python dependencies:
47```bash
48cd benchcompress
49pip install -e .
51benchcompress --help
52benchcompress list
53benchcompress run --help
54```
562. Install web UI dependencies:
57```bash
58cd web-ui
59npm install
60```
623. Run web UI locally:
63```bash
64cd web-ui
65npm run dev
66```
68### Code Formatting
70This project uses pre-commit hooks to automatically check format code before each commit. The formatting includes:
71- Python code formatting using black
72- TypeScript/JavaScript code formatting using npm scripts
73- C++ code formatting using clang-format
75To set up the pre-commit hooks after cloning the repository:
771. Install pre-commit:
78```bash
79pip install pre-commit
80```
822. Install the git hook scripts:
83```bash
84pre-commit install
85```
87After this setup, code will be automatically checked for formatting when you make a commit.
89Running `./devel/format_code.sh` which will format all code in the repository.