3This guide explains how to contribute new algorithms or datasets to Benchcompress.
5## Overview
7Benchcompress welcomes contributions of new compression algorithms and scientific datasets. The framework is designed to make it easy to add new components while ensuring consistent benchmarking and evaluation.
9## Getting Started
111. Fork and clone the repository:
12```bash
13git clone https://github.com/[your-username]/benchcompress.git
14cd benchcompress
15```
172. Install dependencies:
18```bash
19# Install Python package
20cd benchcompress
21pip install -e .
23# Install pre-commit hooks for code compliance checks
24pip install pre-commit
25pre-commit install
26```
28## Adding a New Algorithm
30New algorithms are added in `benchcompress/src/benchcompress/algorithms/`. Each algorithm should:
321. Create a new directory with:
33 - `__init__.py`: Algorithm implementation
34 - `algorithm-name.md`: Documentation and description
362. In `__init__.py`:
37 - Implement compression/decompression functions
38 - Define metadata (version, tags, compatibility)
39 - Follow existing algorithms as examples
41Example structure:
42```
43algorithms/
44└── my_algorithm/
45 ├── __init__.py
46 └── my_algorithm.md
47```
49## Adding a New Dataset
51New datasets are added in `benchcompress/src/benchcompress/datasets/`. Each dataset should:
531. Create a new directory with:
54 - `__init__.py`: Dataset generation/loading code
55 - `dataset-name.md`: Documentation and description
572. In `__init__.py`:
58 - Implement data generation/loading
59 - Define metadata (version, tags)
60 - Follow existing datasets as examples
62Example structure:
63```
64datasets/
65└── my_dataset/
66 ├── __init__.py
67 └── my_dataset.md
68```
70## Testing Locally
72Run benchmarks for your new component:
73```bash
74benchcompress run --algorithm my_algorithm --dataset my_dataset
75```
77The framework will automatically:
78- Run the benchmarks
79- Verify results by decompressing and comparing with original data
80- Measure compression ratios and throughput
82## Code Formatting
84The project uses specific formatters for each language:
85- Python: black formatter
86- TypeScript/JavaScript: ESLint + Prettier
87- C++: clang-format
89To format your code before committing:
90```bash
91# From project root
92./devel/format_code.sh
93```
95This will format all code according to project standards.
97## Code Compliance
99Pre-commit hooks will check code compliance when you commit changes. They verify:
100- Code formatting
101- Import ordering
102- Type checking
103- Other project-specific rules
105If checks fail, format your code using the format script and try again.
107## Creating a Pull Request
1091. Create a new branch:
110```bash
111git checkout -b add-my-component
112```
1142. Format code and ensure it passes compliance checks:
115```bash
116./devel/format_code.sh
117```
1193. Commit your changes:
120```bash
121git add .
122git commit -m "Add new algorithm/dataset: [name]"
123```
1254. Push to your fork:
126```bash
127git push origin add-my-component
128```
1305. Open a pull request on GitHub with:
131 - Clear description of the new component
132 - Any relevant background or references
133 - Local benchmark results
134 - Confirmation that code is formatted and passes checks
136## Guidelines
138- Follow existing code structure and patterns
139- Include thorough documentation
140- Add appropriate tags for filtering
141- Test compatibility with existing components
142- Format code using provided script
143- Ensure all pre-commit checks pass