MB-71691: Precomputed-query optimization for RaBitQ distance

[Nischal1729]

In certain workloads compute_distance_to_codes_for_list is called dozens of times per query with different code batches but the same query vector and IVF list. Each call re-runs set_query (centroid subtraction, norm computations, query quantization, bitplane rearrangement), which dominates cost for 1-bit codes (~60 us out of ~65 us total at d=2048).

This adds a precomputed path that runs set_query once and caches the result in a caller-owned buffer for reuse. Adds query_bitplanes_size() to return the required buffer size, compute_query_precomputed() to produce the serialized query state, and compute_distance_to_codes_with_precomputed() which accepts the cached buffer and skips set_query. Includes corresponding C API functions.

Notes:

• Buffer carries a self-describing header (magic, version, nb_bits, qb, d, list_no); any mismatch triggers a fresh recompute, preventing silent cross-misuse.
• The 1-bit inline path reproduces distance_to_code_1bit math and must be kept in sync manually. It does NOT L2-clamp (matching the DC).
• The multi-bit path delegates to rabitq_utils::compute_full_multibit_distance (same utility the DC uses) so upstream changes propagate automatically. It DOES L2-clamp.
• centered=false is hardcoded just as in the old function; flipping requires updating the inline loop which only implements the non-centered distance branch.

[Copilot]

Pull request overview

This PR adds an optimization path for IndexIVFRaBitQ that allows callers to reuse a cached, precomputed query state across multiple distance computations for the same query vector and IVF list, reducing repeated set_query overhead (notably for 1-bit codes).

Changes:

• Introduces a self-describing precomputed-query buffer format (header + serialized query factors/bitplanes) and a new compute_distance_to_codes_with_precomputed() API.
• Adds query_bitplanes_size() and quantizer helpers (precomputed_query_size(), compute_query_precomputed()) to size/build the reusable query state.
• Exposes the functionality via new C API entry points.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
faiss/IndexIVFRaBitQ.h	Adds precomputed-query header definition and new precomputed distance API declarations.
faiss/IndexIVFRaBitQ.cpp	Implements buffer sizing and the precomputed distance computation path (inline 1-bit + delegated multi-bit).
faiss/impl/RaBitQuantizer.h	Declares quantizer helpers for serializing query state; adds PrecomputedQueryScalars POD.
faiss/impl/RaBitQuantizer.cpp	Implements query precompute serialization and sizing helper.
c_api/IndexIVF_c_ex.h	Declares C API for querying buffer size and computing distances with precomputed state.
c_api/IndexIVF_c_ex.cpp	Implements the new C API wrappers for IndexIVFRaBitQ.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.