Contributing to Benchcompress#

This guide explains how to contribute new algorithms or datasets to Benchcompress.

Overview#

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

Getting Started#

1. Fork and clone the repository:

git clone https://github.com/[your-username]/benchcompress.git
cd benchcompress

2. Install dependencies:

# Install Python package
cd benchcompress
pip install -e .

# Install pre-commit hooks for code compliance checks
pip install pre-commit
pre-commit install

Adding a New Algorithm#

New algorithms are added in benchcompress/src/benchcompress/algorithms/. Each algorithm should:

1. Create a new directory with:

   • __init__.py: Algorithm implementation
   • algorithm-name.md: Documentation and description

2. In __init__.py:

   • Implement compression/decompression functions
   • Define metadata (version, tags, compatibility)
   • Follow existing algorithms as examples

Example structure:

algorithms/
└── my_algorithm/
    ├── __init__.py
    └── my_algorithm.md

Adding a New Dataset#

New datasets are added in benchcompress/src/benchcompress/datasets/. Each dataset should:

1. Create a new directory with:

   • __init__.py: Dataset generation/loading code
   • dataset-name.md: Documentation and description

2. In __init__.py:

   • Implement data generation/loading
   • Define metadata (version, tags)
   • Follow existing datasets as examples

Example structure:

datasets/
└── my_dataset/
    ├── __init__.py
    └── my_dataset.md

Testing Locally#

Run benchmarks for your new component:

benchcompress run --algorithm my_algorithm --dataset my_dataset

The framework will automatically:

• Run the benchmarks
• Verify results by decompressing and comparing with original data
• Measure compression ratios and throughput

Code Formatting#

The project uses specific formatters for each language:

• Python: black formatter
• TypeScript/JavaScript: ESLint + Prettier
• C++: clang-format

To format your code before committing:

# From project root
./devel/format_code.sh

This will format all code according to project standards.

Code Compliance#

Pre-commit hooks will check code compliance when you commit changes. They verify:

• Code formatting
• Import ordering
• Type checking
• Other project-specific rules

If checks fail, format your code using the format script and try again.

Creating a Pull Request#

1. Create a new branch:

git checkout -b add-my-component

2. Format code and ensure it passes compliance checks:

./devel/format_code.sh

3. Commit your changes:

git add .
git commit -m "Add new algorithm/dataset: [name]"

4. Push to your fork:

git push origin add-my-component

5. Open a pull request on GitHub with:
   • Clear description of the new component
   • Any relevant background or references
   • Local benchmark results
   • Confirmation that code is formatted and passes checks

Guidelines#

• Follow existing code structure and patterns
• Include thorough documentation
• Add appropriate tags for filtering
• Test compatibility with existing components
• Format code using provided script
• Ensure all pre-commit checks pass