diskann_quantization/multi_vector/distance/mod.rs
1// Copyright (c) Microsoft Corporation. All rights reserved.
2// Licensed under the MIT license.
3
4//! Distance computation for multi-vector representations.
5//!
6//! Provides asymmetric distance primitives for multi-vector search:
7//!
8//! - [`MaxSim`]: Per-query-vector maximum similarities.
9//! - [`Chamfer`]: Sum of MaxSim scores (asymmetric Chamfer distance).
10//! - [`QueryComputer`]: Architecture-dispatched query computer backed by
11//! SIMD-accelerated block-transposed kernels.
12//!
13//! The fallback path uses a double-loop kernel over
14//! [`InnerProduct`](diskann_vector::distance::InnerProduct). The optimised
15//! path (via [`QueryComputer`]) uses block-transposed layout with
16//! cache-tiled SIMD micro-kernels.
17//!
18//! # Example
19//!
20//! ```
21//! use diskann_quantization::multi_vector::{
22//! distance::{Chamfer, MaxSim, QueryMatRef},
23//! MatRef, Standard,
24//! };
25//! use diskann_vector::{DistanceFunctionMut, PureDistanceFunction};
26//!
27//! // Query: 2 vectors of dim 3 (wrapped as QueryMatRef)
28//! let query_data = [1.0f32, 0.0, 0.0, 0.0, 1.0, 0.0];
29//! let query: QueryMatRef<_> = MatRef::new(
30//! Standard::new(2, 3).unwrap(),
31//! &query_data,
32//! ).unwrap().into();
33//!
34//! // Doc: 2 vectors of dim 3
35//! let doc_data = [1.0f32, 0.0, 0.0, 0.0, 0.0, 1.0];
36//! let doc = MatRef::new(
37//! Standard::new(2, 3).unwrap(),
38//! &doc_data,
39//! ).unwrap();
40//!
41//! // Chamfer distance (sum of max similarities)
42//! let chamfer_dist = Chamfer::evaluate(query, doc);
43//!
44//! // MaxSim (per-query-vector scores)
45//! let mut scores = vec![0.0f32; 2];
46//! let mut max_sim = MaxSim::new(&mut scores).unwrap();
47//! max_sim.evaluate(query, doc);
48//! // scores[0] = -1.0 (query[0] matches doc[0]: negated max inner product)
49//! // scores[1] = 0.0 (query[1] has no good match: max IP was 0)
50//! ```
51
52mod fallback;
53mod kernels;
54mod max_sim;
55mod query_computer;
56
57pub use fallback::QueryMatRef;
58pub use max_sim::{Chamfer, MaxSim, MaxSimError};
59pub use query_computer::QueryComputer;