update README
1 changed file+50−22
README.mdmodified+50−22View file
@@ -6,33 +6,62 @@ Latest benchmark results: https://magland.github.io/zia/
66
77 ## Overview
88
9-Zia provides systematic benchmarking of compression methods for numeric arrays, measuring:
10-- Compression ratio
11-- Encoding throughput (MB/s)
12-- Decoding throughput (MB/s)
9+Zia is a comprehensive benchmarking framework for evaluating compression algorithms on numeric array datasets. The system follows an automated workflow:
1310
14-## Repository Structure
11+1. **Defining Components**
12+ - Algorithms are implemented in `zia_benchmark/src/zia_benchmark/algorithms/`
13+ - Datasets are defined in `zia_benchmark/src/zia_benchmark/datasets/`
14+ - Each component specifies metadata like version, tags, and compatibility requirements
1515
16-Key components are located in the `zia_benchmark/src/zia_benchmark/` directory:
16+2. **Automated Benchmarking**
17+ - Benchmarks run automatically via GitHub Actions on pushes to main branch
18+ - For each compatible algorithm-dataset pair, measures:
19+ - Compression ratio
20+ - Encoding throughput (MB/s)
21+ - Decoding throughput (MB/s)
22+ - Results are verified by decompressing and comparing with original data
1723
18-- Algorithms: `/algorithms/`
19- - LZMA: `/algorithms/lzma/`
20- - Zstandard: `/algorithms/zstd/`
21- - ZLIB: `/algorithms/zlib/`
22- - Simple ANS: `/algorithms/simple_ans/`
23- - etc.
24+3. **Result Storage**
25+ - Results are committed to a dedicated `benchmark-results` branch
26+ - Local and remote caching system prevents redundant rerunning of benchmarks (only modified or added components are re-benchmarked)
27+ - Caching is based on algorithm and dataset versions
2428
25-- Datasets: `/datasets/`
26- - Synthetic data generators:
27- - `/datasets/bernoulli/`: Binary random data
28- - `/datasets/gaussian/`: Normal distribution samples
29- - Real data: `/datasets/real/`
30- - etc.
29+4. **Web Interface**
30+ - Interactive visualization at https://magland.github.io/zia/
31+ - Filter and sort results by dataset or algorithm
32+ - Visual charts for comparing performance metrics
33+ - Export results to CSV for further analysis
3134
32-- Core functionality:
33- - `run_benchmarks.py`: Main benchmarking engine
35+## For developers
3436
35-## Development
37+The project consists of two main components:
38+
39+- `zia_benchmark/`: Python package containing the core benchmarking framework, algorithms, and datasets
40+- `web-ui/`: React-based web interface for visualizing benchmark results
41+
42+### Local Development Setup
43+
44+1. Install Python dependencies:
45+```bash
46+cd zia_benchmark
47+pip install -e .
48+
49+zia-benchmark --help
50+zia-benchmark list
51+zia-benchmark run --help
52+```
53+
54+2. Install web UI dependencies:
55+```bash
56+cd web-ui
57+npm install
58+```
59+
60+3. Run web UI locally:
61+```bash
62+cd web-ui
63+npm run dev
64+```
3665
3766 ### Code Formatting
3867
@@ -53,4 +82,3 @@ pre-commit install
5382 ```
5483
5584 After this setup, code will be automatically formatted when you make a commit.
56-