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