Module turboquant 

TurboQuant KV cache compression — CPU reference implementation.

Implements the TurboQuant_mse algorithm:

1. Walsh-Hadamard rotation for incoherence
2. Per-head norm extraction
3. Lloyd-Max scalar quantization against N(0,1) codebooks

This module is CPU-only math — no Metal GPU dispatch.

Structs

TurboQuantConfig

Configuration for TurboQuant quantization.

Enums

BitWidth

Quantization bit-width for TurboQuant.

Constants

CODEBOOK_2BIT

2-bit Lloyd-Max centroids for N(0,1): 4 reconstruction levels.

CODEBOOK_3BIT

3-bit Lloyd-Max centroids for N(0,1): 8 reconstruction levels.

CODEBOOK_4BIT

4-bit Lloyd-Max centroids for N(0,1): 16 reconstruction levels.

CODEBOOK_HB_5BIT

5-bit Lloyd-Max centroids for N(0,1): 32 reconstruction levels. Mirrors flash_attn_vec_tq_hb.metal::CODEBOOK_HB_5BIT.

CODEBOOK_HB_6BIT

6-bit Lloyd-Max centroids for N(0,1): 64 reconstruction levels. Mirrors flash_attn_vec_tq_hb.metal::CODEBOOK_HB_6BIT.

CODEBOOK_HB_8BIT

8-bit Lloyd-Max centroids for N(0,1): 256 reconstruction levels. Range: [-5.0652659, +5.0652659]. Symmetry error: 3.41e-10. Mirrors flash_attn_vec_tq_hb.metal::CODEBOOK_HB_8BIT and hadamard_quantize_kv_fast.metal::CODEBOOK_8BIT.

TBQ_SIGNS_256

D1 sign mask for the SRHT pre-multiplication, D=256 path.

TBQ_SIGNS_512

D1 sign mask for the SRHT pre-multiplication, D=512 path.

Functions

apply_d1_sign_mask_inplace

Apply D1 sign mask in-place per the SRHT convention.

compute_lloyd_max_beta_codebook

Compute Lloyd-Max codebook for Beta((d-1)/2, (d-1)/2) scaled to [-1, 1].

compute_lloyd_max_codebook

Compute Lloyd-Max codebook for N(0,1) with the given number of levels.

fwht_inplace

In-place normalized Fast Walsh-Hadamard Transform.

hb_centroid

HB codebook lookup helper.

hb_nearest_centroid

HB nearest-centroid encoder (CPU-side mirror of the Metal encoder kernel).

turboquant_dequantize

Dequantize a TurboQuant-compressed head vector.

turboquant_hb_encode_d256

Higher-bit (5/6/8-bit) CPU encoder for D=256 — byte-equivalent mirror of hadamard_quantize_kv_fast.metal::hadamard_quantize_kv_hb<256>.

turboquant_quantize

Quantize a single head vector using TurboQuant_mse.