Metadata-Version: 2.4
Name: chimp-encoding
Version: 0.2.0
Summary: Chimp time-series floating point compression for Python
Author: Hugo
License-Expression: MIT
License-File: LICENSE
Keywords: chimp,compression,floating-point,time-series
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# chimp-encoding

Chimp time-series floating point compression for Python.

A Python port of the [Chimp](https://github.com/panagiotisl/chimp) algorithm for lossless compression of floating-point time-series data. Supports both 64-bit (double) and 32-bit (float) variants, in base mode and history-based (Chimp128/ChimpN) mode.

## Installation

```bash
pip install chimp-encoding
```

## Usage

### Encoding and decoding 64-bit doubles

```python
from chimp_encoding import ChimpEncoder, ChimpDecoder

# Encode
encoder = ChimpEncoder()
for value in [23.5, 23.6, 23.4, 24.0, 22.9]:
    encoder.add_value(value)
encoder.close()

compressed = encoder.get_bytes()
print(f"Compressed to {len(compressed)} bytes")

# Decode
decoder = ChimpDecoder(compressed)
values = decoder.get_values()
print(values)  # [23.5, 23.6, 23.4, 24.0, 22.9]
```

### Using Chimp128 (history-based, better compression)

```python
from chimp_encoding import ChimpNEncoder, ChimpNDecoder

encoder = ChimpNEncoder(previous_values=128)
for value in data:
    encoder.add_value(value)
encoder.close()

decoder = ChimpNDecoder(encoder.get_bytes(), previous_values=128)
values = decoder.get_values()
```

### 32-bit float variants

```python
from chimp_encoding import Chimp32Encoder, Chimp32Decoder
from chimp_encoding import ChimpN32Encoder, ChimpN32Decoder
```

### CLI

```bash
# Encode values to hex
chimp encode 23.5 23.6 23.4 24.0 22.9

# Encode to file
chimp encode 23.5 23.6 23.4 -o compressed.bin

# Decode from hex
chimp decode --hex "4037800000000000..."

# Decode from file
chimp decode compressed.bin

# Use different variants
chimp encode --variant chimp128 23.5 23.6 23.4
chimp decode --variant chimp128 --hex "..."
```

## Variants

| Variant | Class | Description |
|---------|-------|-------------|
| Chimp | `ChimpEncoder` / `ChimpDecoder` | Base 64-bit, XOR with previous value |
| Chimp32 | `Chimp32Encoder` / `Chimp32Decoder` | Base 32-bit |
| ChimpN | `ChimpNEncoder` / `ChimpNDecoder` | 64-bit with N-value history (default N=128) |
| ChimpN32 | `ChimpN32Encoder` / `ChimpN32Decoder` | 32-bit with N-value history (default N=64) |

## License

MIT
