quantbench-engine 0.1.0__py3-none-any.whl

quantbench/quant/packing/sparse_pack.py

@@ -0,0 +1,170 @@
+"""2:4 Structured Sparsity metadata bit-packing and matrix compression runtime.
+
+Implements the NVIDIA Ampere/Ada/Hopper Sparse Tensor Core data layout:
+- Invariant: In every consecutive chunk of 4 values along the row dimension, exactly 2
+  values must be retained (50% sparsity).
+- Retained values are stored in a dense condensed matrix of shape (M, N / 2).
+- Column position indices (0, 1, 2, or 3) require log2(4) = 2 bits each.
+- Two 2-bit indices for a 4-element block fit in 4 bits (1 nibble).
+- Two consecutive 4-element blocks (8 dense elements, 4 retained non-zeros) pack into
+  a single uint8 byte!
+
+Byte layout for two 4-element blocks (A and B):
+- Bits [0:1]: Block A, first non-zero index (0..3)
+- Bits [2:3]: Block A, second non-zero index (0..3)
+- Bits [4:5]: Block B, first non-zero index (0..3)
+- Bits [6:7]: Block B, second non-zero index (0..3)
+"""
+
+from __future__ import annotations
+
+import torch
+
+
+def pack_2_4_indices(indices: torch.Tensor) -> torch.Tensor:
+    """Pack 2-bit position indices for 2:4 structured sparsity into a uint8 tensor.
+
+    Args:
+        indices: Tensor of shape (..., K) where K is a multiple of 4, containing
+            position indices in {0, 1, 2, 3}. Every pair (2k, 2k+1) represents
+            the two non-zero positions in a 4-element block.
+
+    Returns:
+        Packed uint8 tensor of shape (..., K // 4).
+    """
+    if indices.shape[-1] % 4 != 0:
+        raise ValueError(
+            f"Last dimension must be a multiple of 4 (representing pairs of 4-element blocks), "
+            f"got {indices.shape[-1]}."
+        )
+
+    i32 = indices.to(torch.int32)
+    if (i32 < 0).any() or (i32 > 3).any():
+        raise ValueError("2:4 sparsity position indices must be strictly within {0, 1, 2, 3}.")
+
+    # Each byte holds 4 indices: (idx0, idx1) from Block A, and (idx2, idx3) from Block B
+    idx0 = i32[..., 0::4]
+    idx1 = i32[..., 1::4]
+    idx2 = i32[..., 2::4]
+    idx3 = i32[..., 3::4]
+
+    packed = (
+        (idx0 & 0x03)
+        | ((idx1 & 0x03) << 2)
+        | ((idx2 & 0x03) << 4)
+        | ((idx3 & 0x03) << 6)
+    )
+    return packed.to(torch.uint8)
+
+
+def unpack_2_4_indices(packed: torch.Tensor) -> torch.Tensor:
+    """Unpack packed uint8 metadata tensor back into 2-bit position indices.
+
+    Args:
+        packed: Tensor of dtype torch.uint8 and shape (..., M).
+
+    Returns:
+        Tensor of dtype torch.int8 and shape (..., M * 4) containing indices in {0, 1, 2, 3}.
+    """
+    if packed.dtype != torch.uint8:
+        raise TypeError(f"Packed tensor must have dtype torch.uint8, got {packed.dtype}.")
+
+    p32 = packed.to(torch.int32)
+    idx0 = p32 & 0x03
+    idx1 = (p32 >> 2) & 0x03
+    idx2 = (p32 >> 4) & 0x03
+    idx3 = (p32 >> 6) & 0x03
+
+    interleaved = torch.stack([idx0, idx1, idx2, idx3], dim=-1)
+    flat_shape = list(interleaved.shape[:-2]) + [interleaved.shape[-2] * 4]
+    return interleaved.view(flat_shape).to(torch.int8)
+
+
+def prune_and_compress_2_4(
+    weight: torch.Tensor,
+) -> tuple[torch.Tensor, torch.Tensor]:
+    """Prune a dense matrix to 2:4 structured sparsity and pack its values and metadata.
+
+    For every block of 4 elements along the last dimension:
+    1. Finds the 2 elements with largest absolute magnitude.
+    2. Stores their values in condensed_values of shape (..., N // 2).
+    3. Encodes their original within-block positions into packed_metadata of shape (..., N // 8).
+
+    Args:
+        weight: Dense weight tensor with last dimension divisible by 8.
+
+    Returns:
+        Tuple of (condensed_values, packed_metadata).
+        condensed_values has shape (..., N // 2) and same dtype as input.
+        packed_metadata has shape (..., N // 8) and dtype torch.uint8.
+    """
+    orig_shape = weight.shape
+    n = orig_shape[-1]
+    if n % 8 != 0:
+        raise ValueError(f"Last dimension must be divisible by 8 for 2:4 byte alignment, got {n}.")
+
+    # Reshape into blocks of 4
+    num_blocks = n // 4
+    blocks = weight.view(*orig_shape[:-1], num_blocks, 4)
+
+    # Find top 2 values by absolute magnitude in each block of 4
+    abs_blocks = blocks.abs()
+    # topk returns values and indices sorted descending
+    _, top2_indices = torch.topk(abs_blocks, k=2, dim=-1, largest=True, sorted=True)
+
+    # Sort indices ascending to preserve relative left-to-right order
+    sorted_indices, _ = torch.sort(top2_indices, dim=-1)
+
+    # Gather the top 2 values
+    condensed = torch.gather(blocks, dim=-1, index=sorted_indices)
+
+    # Flatten condensed values to (..., N // 2)
+    condensed_shape = list(orig_shape[:-1]) + [n // 2]
+    condensed_values = condensed.view(condensed_shape)
+
+    # Flatten indices to (..., N // 2) and pack into uint8 bytes
+    flat_indices = sorted_indices.view(condensed_shape)
+    packed_metadata = pack_2_4_indices(flat_indices)
+
+    return condensed_values, packed_metadata
+
+
+def decompress_2_4(
+    condensed_values: torch.Tensor,
+    packed_metadata: torch.Tensor,
+    original_shape: tuple[int, ...] | torch.Size,
+) -> torch.Tensor:
+    """Decompress condensed values and packed metadata back to a sparse 2:4 tensor.
+
+    Args:
+        condensed_values: Tensor of shape (..., N // 2).
+        packed_metadata: Tensor of shape (..., N // 8) and dtype torch.uint8.
+        original_shape: Shape of original dense tensor to reconstruct (..., N).
+
+    Returns:
+        Reconstructed tensor with exact 2:4 sparsity (exactly 2 non-zeros per 4 elements).
+    """
+    n = original_shape[-1]
+    if n % 8 != 0:
+        raise ValueError(f"Original shape last dimension must be divisible by 8, got {n}.")
+
+    num_blocks = n // 4
+    unpacked_indices = unpack_2_4_indices(packed_metadata)
+
+    # Reshape condensed and indices to (..., num_blocks, 2)
+    val_blocks = condensed_values.view(*original_shape[:-1], num_blocks, 2)
+    idx_blocks = unpacked_indices.view(*original_shape[:-1], num_blocks, 2).to(torch.int64)
+
+    # Allocate zero tensor for blocks (..., num_blocks, 4)
+    reconstructed_blocks = torch.zeros(
+        *original_shape[:-1],
+        num_blocks,
+        4,
+        dtype=condensed_values.dtype,
+        device=condensed_values.device,
+    )
+
+    # Scatter condensed values back into their exact positions
+    reconstructed_blocks.scatter_(dim=-1, index=idx_blocks, src=val_blocks)
+
+    return reconstructed_blocks.view(original_shape)

quantbench/quant/packing/ternary_pack.py

@@ -0,0 +1,193 @@
+"""BitNet 1.58b ternary bit-packing runtime for sub-byte quantization.
+
+Packs ternary weights in {-1, 0, +1} into compact uint8 byte containers.
+Supports two complementary packing representations:
+1. '2bit' (Default, hardware SIMD-friendly):
+   - Maps {-1 -> 0, 0 -> 1, +1 -> 2} (biased offset by +1).
+   - Packs 4 ternary values into 1 byte (2 bits per value).
+   - Enables fast parallel bitshift and masking instructions on CPU/GPU.
+   - Delivers an 8x memory reduction over FP16 and 4x over INT8.
+
+2. 'base3' (High-density Radix-3):
+   - Because 3^5 = 243 < 256, packs 5 ternary values into 1 byte.
+   - Theoretical information-theoretic density limit (~1.58 bits per weight).
+"""
+
+from __future__ import annotations
+
+import torch
+
+
+def pack_ternary_quad(v0: int, v1: int, v2: int, v3: int) -> int:
+    """Pack four ternary values {-1, 0, +1} into a single 8-bit unsigned byte.
+
+    Uses biased representation: u = v + 1 in {0, 1, 2}.
+    """
+    for v in (v0, v1, v2, v3):
+        if v not in (-1, 0, 1):
+            raise ValueError(f"Ternary values must be in {{-1, 0, 1}}, got {v}.")
+    u0 = v0 + 1
+    u1 = v1 + 1
+    u2 = v2 + 1
+    u3 = v3 + 1
+    return (u0 & 0x03) | ((u1 & 0x03) << 2) | ((u2 & 0x03) << 4) | ((u3 & 0x03) << 6)
+
+
+def unpack_ternary_quad(byte: int) -> tuple[int, int, int, int]:
+    """Unpack a single 8-bit unsigned byte into four ternary values {-1, 0, +1}."""
+    u0 = byte & 0x03
+    u1 = (byte >> 2) & 0x03
+    u2 = (byte >> 4) & 0x03
+    u3 = (byte >> 6) & 0x03
+    return u0 - 1, u1 - 1, u2 - 1, u3 - 1
+
+
+def pack_ternary(
+    tensor: torch.Tensor,
+    mode: str = "2bit",
+    dim: int = -1,
+) -> tuple[torch.Tensor, int]:
+    """Vectorized packing of ternary {-1, 0, +1} weights into a uint8 tensor.
+
+    Args:
+        tensor: Integer or float tensor containing ternary values {-1, 0, 1}.
+        mode: Packing mode:
+            - '2bit': 4 ternary weights per byte (standard SIMD bitshift).
+            - 'base3': 5 ternary weights per byte (Radix-3 maximal density).
+        dim: Dimension along which to pack. Defaults to last dimension (-1).
+
+    Returns:
+        Tuple of (packed_uint8_tensor, original_dim_length).
+    """
+    if mode not in ("2bit", "base3"):
+        raise ValueError(f"Unknown packing mode '{mode}'. Choose '2bit' or 'base3'.")
+
+    t_int = tensor.round().to(torch.int32)
+    valid_mask = (t_int == -1) | (t_int == 0) | (t_int == 1)
+    if not valid_mask.all():
+        raise ValueError("Input tensor contains values outside the ternary set {-1, 0, 1}.")
+
+    dim = dim if dim >= 0 else tensor.ndim + dim
+    orig_len = tensor.shape[dim]
+
+    if dim != tensor.ndim - 1:
+        t_int = t_int.transpose(dim, -1)
+
+    # Offset to non-negative range: {-1, 0, 1} -> {0, 1, 2}
+    u = t_int + 1
+
+    if mode == "2bit":
+        chunk_size = 4
+        rem = orig_len % chunk_size
+        if rem != 0:
+            pad_len = chunk_size - rem
+            pad_shape = list(u.shape[:-1]) + [pad_len]
+            # Pad with 1 (which maps to ternary 0 after offset)
+            pad_tensor = torch.ones(pad_shape, dtype=u.dtype, device=u.device)
+            u = torch.cat([u, pad_tensor], dim=-1)
+
+        v0 = u[..., 0::4]
+        v1 = u[..., 1::4]
+        v2 = u[..., 2::4]
+        v3 = u[..., 3::4]
+
+        packed = (v0 & 0x03) | ((v1 & 0x03) << 2) | ((v2 & 0x03) << 4) | ((v3 & 0x03) << 6)
+        packed_uint8 = packed.to(torch.uint8)
+
+    else:  # base3: 5 weights per byte
+        chunk_size = 5
+        rem = orig_len % chunk_size
+        if rem != 0:
+            pad_len = chunk_size - rem
+            pad_shape = list(u.shape[:-1]) + [pad_len]
+            pad_tensor = torch.ones(pad_shape, dtype=u.dtype, device=u.device)
+            u = torch.cat([u, pad_tensor], dim=-1)
+
+        v0 = u[..., 0::5]
+        v1 = u[..., 1::5]
+        v2 = u[..., 2::5]
+        v3 = u[..., 3::5]
+        v4 = u[..., 4::5]
+
+        packed = v0 + (3 * v1) + (9 * v2) + (27 * v3) + (81 * v4)
+        packed_uint8 = packed.to(torch.uint8)
+
+    if dim != tensor.ndim - 1:
+        packed_uint8 = packed_uint8.transpose(dim, -1)
+
+    return packed_uint8, orig_len
+
+
+def unpack_ternary(
+    packed: torch.Tensor,
+    original_len: int | None = None,
+    mode: str = "2bit",
+    dim: int = -1,
+) -> torch.Tensor:
+    """Vectorized unpacking of packed uint8 tensor back into ternary {-1, 0, +1} values.
+
+    Args:
+        packed: Tensor of dtype torch.uint8 containing packed ternary values.
+        original_len: Optional original dimension length to trim padding.
+        mode: Packing mode used ('2bit' or 'base3').
+        dim: Dimension along which elements were packed.
+
+    Returns:
+        Unpacked tensor of dtype torch.int8 containing values strictly in {-1, 0, 1}.
+    """
+    if packed.dtype != torch.uint8:
+        raise TypeError(f"Packed tensor must have dtype torch.uint8, got {packed.dtype}.")
+
+    dim = dim if dim >= 0 else packed.ndim + dim
+    if dim != packed.ndim - 1:
+        packed = packed.transpose(dim, -1)
+
+    p32 = packed.to(torch.int32)
+
+    if mode == "2bit":
+        u0 = p32 & 0x03
+        u1 = (p32 >> 2) & 0x03
+        u2 = (p32 >> 4) & 0x03
+        u3 = (p32 >> 6) & 0x03
+
+        # Subtract offset: {0, 1, 2} -> {-1, 0, 1}
+        v0 = u0 - 1
+        v1 = u1 - 1
+        v2 = u2 - 1
+        v3 = u3 - 1
+
+        interleaved = torch.stack([v0, v1, v2, v3], dim=-1)
+        flat_shape = list(interleaved.shape[:-2]) + [interleaved.shape[-2] * 4]
+        unpacked = interleaved.view(flat_shape).to(torch.int8)
+
+    elif mode == "base3":
+        # Extract via radix-3 integer division and modulo
+        u0 = p32 % 3
+        rem1 = p32 // 3
+        u1 = rem1 % 3
+        rem2 = rem1 // 3
+        u2 = rem2 % 3
+        rem3 = rem2 // 3
+        u3 = rem3 % 3
+        u4 = rem3 // 3
+
+        v0 = u0 - 1
+        v1 = u1 - 1
+        v2 = u2 - 1
+        v3 = u3 - 1
+        v4 = u4 - 1
+
+        interleaved = torch.stack([v0, v1, v2, v3, v4], dim=-1)
+        flat_shape = list(interleaved.shape[:-2]) + [interleaved.shape[-2] * 5]
+        unpacked = interleaved.view(flat_shape).to(torch.int8)
+
+    else:
+        raise ValueError(f"Unknown packing mode '{mode}'. Choose '2bit' or 'base3'.")
+
+    if original_len is not None:
+        unpacked = unpacked[..., :original_len]
+
+    if dim != packed.ndim - 1:
+        unpacked = unpacked.transpose(dim, -1)
+
+    return unpacked

quantbench_engine-0.1.0.dist-info/METADATA

@@ -0,0 +1,276 @@
+Metadata-Version: 2.5
+Name: quantbench-engine
+Version: 0.1.0
+Summary: First-principles LLM quantization engine, bit-packing runtimes, 2:4 sparsity, and Quality-vs-Speed Pareto evaluation benchmark.
+Project-URL: Homepage, https://github.com/Prajwal7-2002/quantbench
+Project-URL: Documentation, https://prajwal7-2002.github.io/quantbench/
+Project-URL: Repository, https://github.com/Prajwal7-2002/quantbench.git
+Project-URL: Issues, https://github.com/Prajwal7-2002/quantbench/issues
+Author-email: Prajwal Pujari <prajwalpujari16@gmail.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: awq,benchmark,bitnet,fp8,gptq,inference,int4,int8,llm,petaflop,quantization,serving,smoothquant,sparsity
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: System :: Benchmark
+Classifier: Topic :: System :: Hardware
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.6
+Requires-Dist: rich>=13
+Requires-Dist: safetensors>=0.4.3
+Requires-Dist: torch>=2.4.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# quantbench ⚖️
+
+[![CI](https://github.com/Prajwal7-2002/quantbench/actions/workflows/ci.yml/badge.svg)](https://github.com/Prajwal7-2002/quantbench/actions)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/)
+[![Hardware](https://img.shields.io/badge/Hardware-CPU_%26_GPU-teal.svg)](#)
+
+A **unified, first-principles quantization engine, bit-packing runtime, 2:4 sparsity toolkit, and Quality-vs-Speed Pareto evaluation benchmark** in pure Python and PyTorch.
+
+Most developers treat LLM quantization as a black box: they download GGUF or AWQ checkpoints without knowing how scales and zero-points are calculated, how 4-bit signed integers are packed into memory bytes, or why activation outliers in attention layers make naive INT8 quantization collapse.
+
+`quantbench` implements these production algorithms from scratch with **radical transparency and zero compiled C++/CUDA dependencies**, and provides a benchmark CLI that measures empirical perplexity degradation alongside generation throughput.
+
+---
+
+## ⚡ Core Architecture
+
+```
+┌────────────────────────────────────────────────────────────────────────────────────────┐
+│                                  quantbench                                            │
+│            (Single Unified Repository: First-Principles Engine + Benchmark)            │
+│                                                                                        │
+│  ┌────────────────────────────────────────┐  ┌───────────────────────────────────────┐ │
+│  │ 1. From-Scratch Quant Engine (quant)   │  │ 2. Drop-in Neural Layers (nn)         │ │
+│  │ • Uniform Affine (Scale & Zero-Point)  │  │ • QuantLinear (PyTorch Module)        │ │
+│  │ • Symmetric AbsMax (Per-Tensor/Channel)│  │ • In-Place Model Converter (Qwen2.5,  │ │
+│  │ • Blockwise (Group Size 32, 64, 128)   │  │   SmolLM2-135M, GPT-2)                │ │
+│  │ • INT4 Nibble Packing (uint8 vectors)  │  │ • Forward GEMM with dynamic dequant   │ │
+│  │ • Sub-2-bit Ternary Packing (BitNet)   │  │ • Layer-by-Layer SQNR Diagnostics     │ │
+│  │ • 2:4 Structured Sparsity (Ampere)     │  │                                       │ │
+│  │ • SmoothQuant Outlier Migration        │  │                                       │ │
+│  │ • AWQ Grid Search & GPTQ Hessian/Chol  │  │                                       │ │
+│  └───────────────────┬────────────────────┘  └───────────────────┬───────────────────┘ │
+│                      │                                           │                     │
+│                      └─────────────────────┬─────────────────────┘                     │
+│                                            │ Powers                                    │
+│                                            ▼                                           │
+│  ┌───────────────────────────────────────────────────────────────────────────────────┐ │
+│  │ 3. Rigorous Evaluation & Profiling (eval & bench)                                 │ │
+│  │ • Perplexity Engine: Sliding-window evaluation on WikiText-2 & C4                 │ │
+│  │ • Diagnostics: SQNR (dB), Max Error, Outlier Dimension Detection                  │ │
+│  │ • Hardware Profiler: servebench bridge (Tokens/sec, TTFT, Peak VRAM in MB)        │ │
+│  │ • Terminal ASCII Pareto Visualizer: Generates live Quality vs Speed tradeoff curve│ │
+│  └───────────────────────────────────────────────────────────────────────────────────┘ │
+└────────────────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📐 Mathematical Foundations
+
+### 1. Affine Asymmetric Quantization
+Quantizes a floating-point tensor $x \in [x_{\min}, x_{\max}]$ into integer range $[q_{\min}, q_{\max}]$:
+$$s = \frac{x_{\max} - x_{\min}}{2^b - 1}, \quad z = \text{round}\left(-\frac{x_{\min}}{s}\right) + q_{\min}$$
+$$q = \text{clamp}\left(\text{round}\left(\frac{x}{s}\right) + z, \; q_{\min}, \; q_{\max}\right)$$
+$$\hat{x} = (q - z) \cdot s$$
+
+### 2. Symmetric AbsMax Quantization
+Centers dynamic range at zero ($z = 0$), enabling direct hardware integer GEMM without per-element zero-point subtractions:
+$$s = \frac{\max(|x|)}{2^{b-1} - 1}, \quad q = \text{clamp}\left(\text{round}\left(\frac{x}{s}\right), \; -2^{b-1}, \; 2^{b-1}-1\right)$$
+$$\hat{x} = q \cdot s$$
+
+### 3. Block-Wise (Group-Wise) Quantization
+Partitions weights into blocks of size $G \in \{32, 64, 128\}$ to isolate channel outliers and preserve precision across wide layers.
+
+### 4. OCP FP8 Emulation
+Bit-exact simulation of **E4M3FN** (higher mantissa precision, range $\pm 448$, no infinity) for GEMM weights/activations and **E5M2** (wider dynamic range $\pm 57344$) for gradients and KV caches.
+
+### 5. Sub-Byte Bit-Packing & 2:4 Sparsity
+Because hardware cannot address sub-byte boundaries, weights are packed into vectorized `uint8` containers:
+* **INT4**: Two 4-bit nibbles packed per byte: `(v0 & 0x0F) | ((v1 & 0x0F) << 4)` ($4\times$ memory compression vs FP16).
+* **BitNet Ternary**: Four $\{-1, 0, 1\}$ weights per byte using offset binary mapping ($8\times$ compression vs FP16).
+* **2:4 Structured Sparsity**: Two non-zero values retained per 4-element block ($50\%$ storage) with 2-bit column positions packed into 4-bit metadata nibbles for Ampere/Ada/Hopper Sparse Tensor Cores ($2\times$ TFLOPS).
+
+---
+
+---
+
+## 📦 Installation
+
+Install `quantbench` directly from PyPI:
+
+```bash
+pip install quantbench
+```
+
+Or using [uv](https://docs.astral.sh/uv/):
+
+```bash
+uv add quantbench
+```
+
+To install from source for development:
+
+```bash
+git clone https://github.com/Prajwal7-2002/quantbench.git
+cd quantbench
+uv sync
+```
+
+---
+
+## 🚀 Quickstart
+
+### Sub-Byte Packing Inspection
+
+Inspect how weights are packed into vectorized byte streams and calculate theoretical compression:
+
+```bash
+# Inspect sub-byte bit layouts and theoretical memory compression
+uv run quantbench pack-inspect --format int4
+uv run quantbench pack-inspect --format ternary
+uv run quantbench pack-inspect --format sparse24
+```
+
+### Running the Test Suite
+
+```bash
+# Run the complete test suite (47 tests, 95% coverage)
+uv run pytest
+```
+
+### Python API Quickstart
+
+```python
+import torch
+import torch.nn as nn
+from quantbench import QuantLinear, convert_model_to_quant
+
+# 1. Convert any standalone nn.Linear to INT4 QuantLinear
+linear = nn.Linear(4096, 4096)
+quant_linear = QuantLinear.from_linear(linear, scheme="int4", group_size=64)
+
+x = torch.randn(2, 4096)
+y = quant_linear(x)  # Dynamic vectorized dequantization forward
+stats = quant_linear.memory_footprint_bytes()
+print(
+    f"Compression: {stats['compression_ratio']:.2f}x "
+    f"({stats['fp16_bytes']} -> {stats['compressed_bytes']} bytes)"
+)
+
+# 2. In-place recursive transformer conversion
+model = MyTransformer()
+converted_model, stats = convert_model_to_quant(
+    model,
+    scheme="int4",
+    group_size=64,
+    exclude_modules=["lm_head"],
+)
+print(
+    f"Compressed {stats['converted_layers']} layers: "
+    f"{stats['orig_memory_mb']} MB -> {stats['quant_memory_mb']} MB "
+    f"({stats['compression_ratio']}x)"
+)
+
+# 3. Advanced Calibration Algorithms (SmoothQuant, AWQ, GPTQ)
+from quantbench import (
+    smooth_linear_weights,
+    extract_activation_channel_scales,
+    search_best_awq_scale,
+    compute_activation_channel_means,
+    gptq_quantize_weights,
+    compute_activation_hessian,
+)
+
+# SmoothQuant: Migrate activation outlier dynamic range to weights
+act_scales = extract_activation_channel_scales(linear, calibration_x)
+w_smoothed, scale = smooth_linear_weights(linear.weight, act_scales, alpha=0.5)
+
+# AWQ: Search optimal per-channel protection scales
+act_means = compute_activation_channel_means(calibration_x)
+best_scale, best_alpha = search_best_awq_scale(linear.weight, act_means, calibration_x)
+
+# GPTQ: Second-order Hessian error compensation with Cholesky damping
+h = compute_activation_hessian(calibration_x, in_features=4096)
+w_gptq = gptq_quantize_weights(linear.weight, h, bits=4, block_size=32, damping_factor=0.01)
+
+# 4. Pareto Quality-vs-Compression Benchmark
+from quantbench import ParetoBenchmark, generate_synthetic_corpus
+
+tokens = generate_synthetic_corpus(vocab_size=32000, seq_length=1024)
+bench = ParetoBenchmark(model, tokens, window_size=512, stride=256)
+points = bench.run_sweep()
+print(bench.render_ascii_table(points))
+```
+
+### CLI Quickstart
+
+```bash
+# Evaluate tensor-level numerical fidelity (SQNR dB)
+uv run quantbench eval --shape 1024x1024
+
+# Run automated Pareto sweep across all precision runtimes
+uv run quantbench pareto --vocab-size 128 --hidden-dim 128 --seq-len 300
+```
+
+---
+
+## 🔬 Executable Examples & Roofline Integration
+
+The repository includes runnable end-to-end scripts demonstrating drop-in inference, advanced calibration, and hardware roofline modeling (integrating with `servebench`):
+
+* **[examples/01_quant_linear_inference.py](examples/01_quant_linear_inference.py)**: Demonstrates converting PyTorch `nn.Linear` layers into INT4 blockwise, BitNet 1.58b ternary, and Ampere 2:4 sparse `QuantLinear` modules, verifying forward pass execution and recursive transformer conversion with `lm_head` float exclusion.
+* **[examples/02_advanced_calibration.py](examples/02_advanced_calibration.py)**: Step-by-step demonstration of SmoothQuant outlier migration (proving exact mathematical continuous invariance), AWQ Frobenius grid search for salient channel protection, and GPTQ second-order Hessian Cholesky damping updates yielding $1.48\times$ error reduction.
+* **[examples/03_servebench_roofline_eval.py](examples/03_servebench_roofline_eval.py)**: Bridges `quantbench` drop-in layers with `servebench`'s hardware roofline model (`HARDWARE_PROFILES`, RTX 3050 192 GB/s, T4 320 GB/s), calculating arithmetic intensity $I = \frac{2}{\text{bytes\_per\_param}}$ FLOPs/byte, decode token latency, and DRAM bandwidth traffic reduction (slashing memory traffic by $73.4\%$ for INT4).
+
+```bash
+uv run python examples/01_quant_linear_inference.py
+uv run python examples/02_advanced_calibration.py
+uv run python examples/03_servebench_roofline_eval.py
+```
+
+---
+
+## 📚 Educational Engineering Guide
+
+For an exhaustive first-principles mathematical and architectural breakdown of quantization, sub-byte bit packing, and hardware sparsity, read [GUIDE.md](GUIDE.md):
+* Exact mathematical proofs (Zero-Preserving Affine Invariant, Optimal Brain Surgeon update derivation).
+* IEEE 754 Banker's rounding drift analysis.
+* OCP FP8 (E4M3FN vs E5M2) analytical software emulation.
+* Bit-level packing mechanics (INT4 two's complement sign extension, BitNet biased SIMD vs Base-3, NVIDIA Ampere 2:4 metadata nibbles).
+* Second-order Hessian error compensation with Cholesky inversion and block updates.
+* Dual-metric Pareto benchmarking (Layer-level SQNR dB + Sliding-Window Perplexity).
+
+---
+
+## 🗺️ Roadmap & Staged Milestones
+
+- [x] **Phase 1: Mathematical Primitives & Invariants**: Affine, AbsMax, Group-wise, and FP8 (E4M3/E5M2) simulation with rigorous error bound verification.
+- [x] **Phase 2: Integer Bit-Packing Runtimes**: Vectorized INT4 nibble packing (`uint8`), BitNet ternary packing, and 2:4 sparsity metadata.
+- [x] **Phase 3: Drop-in Neural Layers**: `QuantLinear` PyTorch module, in-place Hugging Face model converter, and buffer serialization.
+- [x] **Phase 4: Advanced Calibration Algorithms**: SmoothQuant outlier migration, AWQ grid search, and GPTQ second-order Hessian updates.
+- [x] **Phase 5: Perplexity & Evaluation Engine**: Standardized sliding-window perplexity on WikiText-2 and C4.
+- [x] **Phase 6: Pareto Benchmark & Terminal Visualizer**: Quality-vs-compression analysis and terminal Rich Pareto curves.
+- [x] **Phase 7: Public Learning Guide & Packaging**: Comprehensive educational walkthrough and PyPI release.
+- [ ] **Phase 8: Sub-Byte Fused Kernels & KV Cache Quantization**: Analytical Triton kernel emulators for mixed-precision GEMV and INT4 KV-cache compression.
+
+---
+
+## 🤝 Contributing
+
+We welcome contributions that expand educational clarity, add new calibration methods, improve numerical fidelity diagnostics, or introduce new sub-byte bit layouts! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for full development guidelines, testing protocols, and PR standards.
+
+---
+
+## 📜 License
+
+Apache 2.0. See [LICENSE](LICENSE) for details.

quantbench_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+quantbench/__init__.py,sha256=KDbTWGNMAWi0Lwdakzu82pMH9flcQn6aMAlh0OHm_qo,2137
+quantbench/cli.py,sha256=IYS_v8z_THl4DVPHmAjXvz1Gjnlk8isMrYrQW4tLlBk,11309
+quantbench/bench/__init__.py,sha256=Vf-t0YdRnJX97bP-WhnQE-JhKsCEHEUrcNmYCcU5FLw,780
+quantbench/bench/pareto.py,sha256=tuwMoW_onWGkQ0X1eB4PoMyZoNsna-Q-VAwb7jSJEtg,6691
+quantbench/eval/__init__.py,sha256=vRUALVM6ipMaY4Un6M2y9JR8G__GVF06Tr9N4Q_f46Y,935
+quantbench/eval/perplexity.py,sha256=VJL-CZ1qStsbHcPKXO1yco3xlJxbc5ngLOOzQEllGo0,5107
+quantbench/eval/sqnr.py,sha256=wcJeavo2wdnTnaJ-a5zt18XZuC33mQ-wIJXX96fP3Io,2330
+quantbench/nn/__init__.py,sha256=ytAvN-xpfAYjk9z1bAG1TgJSpsSAAdaKq6sErJf-Uao,266
+quantbench/nn/model_convert.py,sha256=e0lvsJaqXt-PBeo-fyud4BQDKuPcZwonQgeiP2rgY9E,3971
+quantbench/nn/quant_linear.py,sha256=roL3IEbQZ0gza59kiMPC5S0XGmwAofgGQhIPHxANfRk,11633
+quantbench/quant/__init__.py,sha256=5xxK-EhOMLUQz7cI8ZpVYKQusHxXxTalwbh8YvEiy4I,1589
+quantbench/quant/affine.py,sha256=mNWy56_EwBR8DBesPfQT1MfJW5so92TeftTrRUYOJ3g,5787
+quantbench/quant/blockwise.py,sha256=riB_A4fFpqBefKnGsAdGiVXVzS4ZDZyBzzfC1bY9mbM,3674
+quantbench/quant/fp8.py,sha256=3FzBJtjUMsxD1YThwi-XH3BWCwfp-IUm6Y5SFu2GoEI,4520
+quantbench/quant/algorithms/__init__.py,sha256=Fb7GYY-W86nNYnNZ2o2-NiduM6QalEjtdi7AmQLUtJo,1368
+quantbench/quant/algorithms/awq.py,sha256=gT14qOG4UdxGpud733lhTemOfTpnGMm0UwPZZ-mG-CI,7107
+quantbench/quant/algorithms/gptq.py,sha256=vfRPq2wfYxtBWFZs4qwRG6TJsRlWu3HudDiKVYVxtBA,7113
+quantbench/quant/algorithms/smoothquant.py,sha256=bMTX12D6kVArTZ3MxPl7e2RDsBB7E-chVLocb_nJlyI,5127
+quantbench/quant/packing/__init__.py,sha256=39NUq9k3W2W-7UzsE_6Pi_feGB9KxbWRotlCSTfL1Us,868
+quantbench/quant/packing/int4_pack.py,sha256=k9bYAW6aRnZVhbtOlXySt5Ak_cRroyLY3Nuw_KKN9ZY,5790
+quantbench/quant/packing/sparse_pack.py,sha256=v-v-rGgedsWT_0OxEZfOjMb5NOFjJmVd-Qw4F4tWYlU,6472
+quantbench/quant/packing/ternary_pack.py,sha256=4VhIf_drzwjqUD9UIYHrkjwybxurGvBuT1k_nF-61qg,6527
+quantbench_engine-0.1.0.dist-info/METADATA,sha256=chC6j3ZOR27tD8cnfcZT7p_QZ5zd6ScSDNO85-K9TX0,15014
+quantbench_engine-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+quantbench_engine-0.1.0.dist-info/entry_points.txt,sha256=Xjmf5qAi3DAjbVsTOD8S-YmFIVegvUlIbUxRtyH-zNY,50
+quantbench_engine-0.1.0.dist-info/licenses/LICENSE,sha256=9oZgYppWR-Mtc05yFDBlD0JCfl-TZZwqH4GgLZ7U3gI,10759
+quantbench_engine-0.1.0.dist-info/RECORD,,

quantbench_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

quantbench_engine-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+quantbench = quantbench.cli:app