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//!
11//! Both are currently implemented using a simple double-loop kernel over
12//! [`InnerProduct`](diskann_vector::distance::InnerProduct).
13//!
14//! # Example
15//!
16//! ```
17//! use diskann_quantization::multi_vector::{
18//! distance::{Chamfer, MaxSim, QueryMatRef},
19//! MatRef, Standard,
20//! };
21//! use diskann_vector::{DistanceFunctionMut, PureDistanceFunction};
22//!
23//! // Query: 2 vectors of dim 3 (wrapped as QueryMatRef)
24//! let query_data = [1.0f32, 0.0, 0.0, 0.0, 1.0, 0.0];
25//! let query: QueryMatRef<_> = MatRef::new(
26//! Standard::new(2, 3).unwrap(),
27//! &query_data,
28//! ).unwrap().into();
29//!
30//! // Doc: 2 vectors of dim 3
31//! let doc_data = [1.0f32, 0.0, 0.0, 0.0, 0.0, 1.0];
32//! let doc = MatRef::new(
33//! Standard::new(2, 3).unwrap(),
34//! &doc_data,
35//! ).unwrap();
36//!
37//! // Chamfer distance (sum of max similarities)
38//! let chamfer_dist = Chamfer::evaluate(query, doc);
39//!
40//! // MaxSim (per-query-vector scores)
41//! let mut scores = vec![0.0f32; 2];
42//! let mut max_sim = MaxSim::new(&mut scores).unwrap();
43//! max_sim.evaluate(query, doc);
44//! // scores[0] = -1.0 (query[0] matches doc[0])
45//! // scores[1] = 0.0 (query[1] has no good match)
46//! ```
47
48mod max_sim;
49mod simple;
50
51pub use max_sim::{Chamfer, MaxSim, MaxSimError};
52pub use simple::QueryMatRef;