research(nightly): LoRANN — IVF with per-cluster SVD score approximation (NeurIPS 2024)

[ruvnet]

Summary

Nightly research branch implementing LoRANN (Jääsaari, Hyvönen, Roos — NeurIPS 2024, arXiv:2410.18926): a clustering-based ANN index that replaces the per-cluster O(d·m) exact scorer with a rank-r SVD factorisation costing O(r(d+m)), followed by exact inner-product reranking.

• Research doc: docs/research/nightly/2026-05-08-lorann/README.md
• ADR: docs/adr/ADR-193-lorann.md
• Crate: crates/ruvector-lorann/ — 5 tests green, cargo build --release clean
• Gist: https://gist.github.com/ruvnet/db102223f89f7c76f04f905d5ca7cd0d

Real benchmark results (x86_64, rustc 1.94.1 release, d=128)

n	Variant	n_probe	Recall@10	QPS	vs FlatExact
5,000	FlatExact	—	100.0%	1,703	1.0×
5,000	LoRANN r=32	8	85.5%	9,928	5.8×
5,000	LoRANN r=32	4	76.1%	14,144	8.5×
20,000	FlatExact	—	100.0%	397	1.0×
20,000	LoRANN r=32	8	64.1%	5,733	13.9×
50,000	FlatExact	—	100.0%	145	1.0×
50,000	LoRANN r=32	8	56.1%	4,993	30.9×
50,000	LoRANN r=32	2	29.5%	8,860	54.9×

Acceptance test: recall@10 = 93.2% on n=2,000, d=64, n_probe=8, rank=32. ✅ PASS

How to run

cargo build --release -p ruvector-lorann
cargo test -p ruvector-lorann        # 5 tests, all green
cargo run --release -p ruvector-lorann --bin lorann-demo
cargo run --release -p ruvector-lorann --bin lorann-demo -- --fast  # <30s

Files changed

crates/ruvector-lorann/
├── Cargo.toml               — workspace crate, nalgebra + rayon + thiserror
└── src/
    ├── lib.rs               — public API + 5 inline unit tests
    ├── config.rs            — LorannConfig with safe defaults
    ├── error.rs             — LorannError enum
    ├── kmeans.rs            — k-means++ Lloyd's (rayon parallel)
    ├── regression.rs        — ClusterModel: truncated SVD via nalgebra 0.33
    ├── index.rs             — FlatExactIndex, LorannIndex, AnnIndex trait
    └── main.rs              — lorann-demo: recall@10 + QPS across 3 corpus sizes

docs/adr/ADR-193-lorann.md
docs/research/nightly/2026-05-08-lorann/README.md

Topic selection

SOTA discovery via goal-planner agent confirmed LoRANN (NeurIPS 2024) as most novel and implementable:

• Not in ruvector (unlike HNSW, DiskANN, RaBitQ, ACORN)
• Fills the IVF gap in the index family
• Complementary to ruvector-rabitq (quantization codec) and ruvector-acorn (filtered search)
• MRL was rejected because ruvector already has partial MRL support; SOAR requires training-time query distribution

ADR: ADR-193

See docs/adr/ADR-193-lorann.md for full context, decision, and alternatives considered.

https://claude.ai/code/session_01YbPfSVaUVL3JVHTQMUVXLP