research(nightly): residual-vector-quantization — pure-Rust RVQ for ANN search

[ruvnet]

Nightly Research: Residual Vector Quantization (RVQ)

Topic: Multi-stage residual codebook compression for ANN search
ADR: ADR-193
Research doc: docs/research/nightly/2026-05-09-residual-vector-quantization/README.md
Crate: crates/ruvector-rvq/

---

What This Adds

A new workspace crate ruvector-rvq implementing Residual Vector Quantization — a multi-stage encoding scheme where each codebook stage quantizes only the residual error from the previous stage. First pure-Rust, no-unsafe, no-BLAS RVQ in the ecosystem.

4 index types sharing the AnnIndex trait:

• FlatF32Index — exact brute-force baseline
• PqIndex — standard flat product quantization (comparison)
• RvqIndex — residual vector quantization with ADC search
• RvqRerankIndex — RVQ + exact rerank (high-recall production path)

---

Real Benchmark Numbers

cargo run --release -p ruvector-rvq --bin rvq-demo

Hardware: x86-64 Linux, rustc release, no external SIMD or BLAS.

Suite: n=20K, D=128, K=64 centroids, 25 Lloyd iterations

Variant	Bytes/vec	R@10	QPS
FlatF32 (exact)	512	100.0%	341
PQ M=8 K=64	8	6.3%	2,918
RVQ S=4 K=64	4	6.4%	1,656
RVQ S=8 K=64	8	6.3%	1,258
RVQ S=8 +rerank×4	520	23.9%	1,185

Key insight: RVQ S=4 matches PQ M=8 recall (6.4% vs 6.3%) at half the per-vector byte cost.
At D=256: RVQ S=4 (9.4%) outperforms PQ M=8 (8.1%) at half the bytes.

Distortion convergence (8 stages, K=64):

Stage	Mean L2²	Reduction
1	47.44	0.0%
4	42.19	11.1%
8	38.35	19.2%

All 8 stages active — no codebook collapse under 10% dropout regularisation.

---

Tests

cargo test -p ruvector-rvq
# 7 tests pass: 6 unit + 1 doc (no mocks, no stubs)
cargo build --release -p ruvector-rvq  # ✓

---

Files

Path	Purpose
crates/ruvector-rvq/src/codebook.rs	Lloyd's k-means + K-means++ init
crates/ruvector-rvq/src/rvq.rs	RvqEncoder + ProductQuantizer + ADC tables
crates/ruvector-rvq/src/index.rs	AnnIndex trait + 4 index types + tests
crates/ruvector-rvq/src/main.rs	Benchmark harness (same-run results)
docs/adr/ADR-193-residual-vector-quantization.md	Architecture Decision Record
docs/research/nightly/2026-05-09-residual-vector-quantization/README.md	Full research document

---

Gist

Note: gh CLI is not available in this environment (no GH_TOKEN).
Run gh gist create --public --desc "ruvector RVQ: Residual Vector Quantization pure Rust ANN vector search 2026" docs/research/nightly/2026-05-09-residual-vector-quantization/README.md locally to publish the SEO gist.

---

Next Steps (roadmap from research doc)

• ADR-194: Integrate RVQ as drop-in PQ replacement in ruvector-diskann
• Increase K to 256 (production-grade recall, needs rayon for training speed)
• IVF-RVQ: coarse IVF quantizer + RVQ fine codes
• SIMD ADC inner loop (AVX2/NEON, expected 3–4× QPS)
• Beam-search encoder for higher-quality codes at encode time

https://claude.ai/code/session_01G4YPX6B9nQPKDfkn9J1vdR

---

Generated by Claude Code