research(nightly): distance-adaptive-beam-search

Cargo.toml

@@ -20,6 +20,7 @@ exclude = ["crates/micro-hnsw-wasm", "crates/ruvector-hyperbolic-hnsw", "crates/
 members = [
     "crates/ruvector-acorn",
     "crates/ruvector-acorn-wasm",
+    "crates/ruvector-adaptive-beam",
     "crates/ruvector-rabitq",
     "crates/ruvector-rabitq-wasm",
     "crates/ruvector-rulake",

crates/ruvector-adaptive-beam/Cargo.toml

@@ -0,0 +1,26 @@
+[package]
+name = "ruvector-adaptive-beam"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+description = "Distance-adaptive beam search for provably accurate graph-based ANN (arXiv:2505.15636)"
+
+[[bin]]
+name = "adaptive-beam-demo"
+path = "src/main.rs"
+
+[[bench]]
+name = "adaptive_beam_bench"
+harness = false
+
+[dependencies]
+rand = { workspace = true }
+rand_distr = { workspace = true }
+thiserror = { workspace = true }
+rayon = { workspace = true }
+
+[dev-dependencies]
+criterion = { workspace = true }

crates/ruvector-adaptive-beam/benches/adaptive_beam_bench.rs

@@ -0,0 +1,48 @@
+use criterion::{criterion_group, criterion_main, BenchmarkId, Criterion, Throughput};
+use rand::SeedableRng;
+use rand::rngs::StdRng;
+use rand_distr::{Distribution, Normal};
+use ruvector_adaptive_beam::graph::build_knn_graph;
+use ruvector_adaptive_beam::{AdaptiveBeamIndex, BeamStopPolicy};
+
+fn make_vecs(n: usize, d: usize, seed: u64) -> Vec<Vec<f32>> {
+    let mut rng = StdRng::seed_from_u64(seed);
+    let normal = Normal::new(0.0f32, 1.0).unwrap();
+    (0..n)
+        .map(|_| (0..d).map(|_| normal.sample(&mut rng)).collect())
+        .collect()
+}
+
+fn bench_policies(c: &mut Criterion) {
+    let n = 2_000;
+    let d = 64;
+    let k = 10;
+    let vecs = make_vecs(n, d, 42);
+    let (nb, ep) = build_knn_graph(&vecs, 12);
+    let idx = AdaptiveBeamIndex::new(vecs, nb, ep);
+    let queries = make_vecs(100, d, 999);
+
+    let mut group = c.benchmark_group("beam_search");
+    group.throughput(Throughput::Elements(queries.len() as u64));
+
+    let cases: &[(BeamStopPolicy, &str)] = &[
+        (BeamStopPolicy::FixedWidth { beam_width: 32 }, "FixedWidth_bw32"),
+        (BeamStopPolicy::DistanceAdaptive { gamma: 1.0 }, "DistAdaptive_g1"),
+        (BeamStopPolicy::AdaptiveWithFloor { gamma: 0.5, min_expansions: 8 }, "AdaptFloor_g05_m8"),
+    ];
+
+    for (policy, name) in cases {
+        let policy = *policy;
+        group.bench_with_input(BenchmarkId::new("search", name), name, |b, _| {
+            b.iter(|| {
+                for q in &queries {
+                    let _ = idx.search(q, k, policy);
+                }
+            });
+        });
+    }
+    group.finish();
+}
+
+criterion_group!(benches, bench_policies);
+criterion_main!(benches);

crates/ruvector-adaptive-beam/src/graph.rs

@@ -0,0 +1,55 @@
+/// k-NN graph construction for AdaptiveBeamIndex.
+///
+/// Builds an exact k-nearest-neighbour graph via parallel exhaustive search.
+/// Exact k-NN gives a navigable NSW structure without approximation artefacts,
+/// making it the fairest baseline for measuring search-policy differences.
+use crate::l2_sq;
+use rayon::prelude::*;
+
+/// Build an exact k-NN graph over `vectors`.
+///
+/// Returns `(adjacency_lists, entry_point_index)`.
+/// Each node i connects to its `max_neighbors` nearest peers (excluding itself).
+/// The entry point is the medoid — the vector closest to the data centroid —
+/// which provides balanced graph traversal from any query direction.
+pub fn build_knn_graph(vectors: &[Vec<f32>], max_neighbors: usize) -> (Vec<Vec<u32>>, u32) {
+    let n = vectors.len();
+    if n == 0 {
+        return (vec![], 0);
+    }
+    if n == 1 {
+        return (vec![vec![]], 0);
+    }
+
+    let neighbors: Vec<Vec<u32>> = (0..n)
+        .into_par_iter()
+        .map(|i| {
+            let mut dists: Vec<(f32, u32)> = (0..n)
+                .filter(|&j| j != i)
+                .map(|j| (l2_sq(&vectors[i], &vectors[j]), j as u32))
+                .collect();
+            dists.sort_by(|a, b| a.0.partial_cmp(&b.0).unwrap_or(std::cmp::Ordering::Equal));
+            dists.truncate(max_neighbors);
+            dists.into_iter().map(|(_, j)| j).collect()
+        })
+        .collect();
+
+    let ep = medoid(vectors);
+    (neighbors, ep)
+}
+
+/// Returns the index of the vector closest to the centroid of `vectors`.
+fn medoid(vectors: &[Vec<f32>]) -> u32 {
+    let n = vectors.len();
+    let dim = vectors[0].len();
+    let centroid: Vec<f32> = (0..dim)
+        .map(|d| vectors.iter().map(|v| v[d]).sum::<f32>() / n as f32)
+        .collect();
+    (0..n)
+        .min_by(|&a, &b| {
+            l2_sq(&vectors[a], &centroid)
+                .partial_cmp(&l2_sq(&vectors[b], &centroid))
+                .unwrap_or(std::cmp::Ordering::Equal)
+        })
+        .unwrap_or(0) as u32
+}