Metadata-Version: 2.4
Name: ctt-compression
Version: 0.1.0
Summary: Extreme post-training neural network compression (~30x ratio) via 2-bit packed non-uniform percentile quantization.
Author-email: Americo Simoes <americo.simoes@proton.me>
License: MIT
Project-URL: Homepage, https://github.com/SimoesCTT/CTT-Extreme-Post-Training-Model-Compression-via-2-Bit-Packed-Non-Uniform-Percentile-Quantization
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.20.0
Requires-Dist: torch>=1.10.0

# 🎧 CTT: Compressed Tensor/Transform

**CTT** is an ultra-lightweight, zero-retraining post-training model compression framework. It achieves extreme model reduction (**~30x compression ratios**) while preserving structural layer integrity and offering instantaneous compression and decompression.

Unlike traditional post-training quantization (PTQ) techniques that require heavy calibration datasets or cause catastrophic accuracy drops, CTT treats weights as an information-theoretic signal payload—combining **percentile outlier shielding**, **dense sub-byte bit-packing**, and **entropy coding**.

---

## 📊 Benchmark Results

Evaluated out-of-the-box on standard torchvision pre-trained models:

| Architecture | Original Size | Compressed Size | Compression Ratio | Avg. Correlation | Compress / Decompress |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **ResNet-18** | 44.63 MB | 1.47 MB | **30.33x** | **0.7326** | 0.82s / 0.28s |
| **ResNet-50** | 97.70 MB | 3.49 MB | **28.01x** | **0.7105** | 1.37s / 0.59s |
| **MobileNet-V2**| 13.50 MB | 0.59 MB | **22.91x** | **0.7526** | 0.22s / 0.13s |

---

## 🚀 How It Works

1. **Percentile Outlier Shielding:** Automatically clips extreme weight spikes using the 99.9th absolute percentile, stabilizing the distribution map.
2. **2-Bit Non-Uniform Quantization:** Maps continuous weights precisely into a 4-level discrete space over $[-1, 1]$.
3. **Dense Bit-Packing:** Shifting math packs four distinct 2-bit values into a single physical byte, bypassing standard hardware memory bloat.
4. **Entropy Encoding:** Passes the packed stream through level-9 `zlib` compression to crush redundant patterns.

---

## 📦 Quick Start

```python
import torch
import torchvision.models as models
from ctt_compressor import CTTCompressor

# Load a pretrained model
model = models.resnet18(weights=models.ResNet18_Weights.DEFAULT)
compressor = CTTCompressor(target_bits=2)

# Compress a layer tensor
tensor_data = model.conv1.weight.detach().cpu().numpy()
compressed_payload = compressor.compress(tensor_data)

# Decompress back to float32 tensor
reconstructed_data = compressor.decompress(compressed_payload)
