research(nightly): dabs-hnsw — Distance Adaptive Beam Search, NeurIPS 2025

Cargo.toml

@@ -18,6 +18,7 @@ exclude = ["crates/micro-hnsw-wasm", "crates/ruvector-hyperbolic-hnsw", "crates/
     # land in iters 92-97.
     "crates/ruos-thermal"]
 members = [
+    "crates/ruvector-dabs",
     "crates/ruvector-acorn",
     "crates/ruvector-acorn-wasm",
     "crates/ruvector-rabitq",

crates/ruvector-dabs/Cargo.toml

@@ -0,0 +1,28 @@
+[package]
+name = "ruvector-dabs"
+version.workspace = true
+edition.workspace = true
+rust-version.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+description = "Distance Adaptive Beam Search (DABS) for HNSW — provably accurate ANN with gamma-parameterized termination (NeurIPS 2025, arXiv:2505.15636)"
+
+[[bin]]
+name = "dabs-demo"
+path = "src/main.rs"
+
+[[bench]]
+name = "dabs_bench"
+harness = false
+
+[dependencies]
+rand = { workspace = true }
+rand_distr = { workspace = true }
+thiserror = { workspace = true }
+
+[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
+rayon = { workspace = true }
+
+[dev-dependencies]
+criterion = { workspace = true }

crates/ruvector-dabs/benches/dabs_bench.rs

@@ -0,0 +1,56 @@
+use criterion::{black_box, criterion_group, criterion_main, BenchmarkId, Criterion};
+use rand::SeedableRng;
+use rand_distr::{Distribution, Normal};
+use ruvector_dabs::{DabsIndex, SearchMode};
+
+fn gen_data(n: usize, dim: usize, seed: u64) -> Vec<Vec<f32>> {
+    let mut rng = rand::rngs::SmallRng::seed_from_u64(seed);
+    let normal = Normal::new(0.0_f32, 1.0).unwrap();
+    (0..n).map(|_| (0..dim).map(|_| normal.sample(&mut rng)).collect()).collect()
+}
+
+fn bench_search(c: &mut Criterion) {
+    let data = gen_data(5_000, 128, 42);
+    let queries = gen_data(50, 128, 99);
+    let index = DabsIndex::build(data, 16).unwrap();
+
+    let mut group = c.benchmark_group("search_5k_d128");
+
+    group.bench_function("flat", |b| {
+        b.iter(|| {
+            for q in &queries {
+                let _ = black_box(index.search(q, 10, SearchMode::Flat).unwrap());
+            }
+        })
+    });
+
+    for ef in [32, 64, 128] {
+        group.bench_with_input(BenchmarkId::new("fixed_ef", ef), &ef, |b, &ef| {
+            b.iter(|| {
+                for q in &queries {
+                    let _ = black_box(index.search(q, 10, SearchMode::FixedEf { ef }).unwrap());
+                }
+            })
+        });
+    }
+
+    for gamma in [0.1_f32, 0.5, 1.0] {
+        group.bench_with_input(
+            BenchmarkId::new("dabs_gamma", format!("{gamma:.1}")),
+            &gamma,
+            |b, &gamma| {
+                b.iter(|| {
+                    for q in &queries {
+                        let _ =
+                            black_box(index.search(q, 10, SearchMode::Dabs { gamma }).unwrap());
+                    }
+                })
+            },
+        );
+    }
+
+    group.finish();
+}
+
+criterion_group!(benches, bench_search);
+criterion_main!(benches);

crates/ruvector-dabs/src/dist.rs

@@ -0,0 +1,86 @@
+//! Distance functions. All operate on f32 slices.
+//! L2-squared is used throughout; the squared form avoids a sqrt while
+//! preserving total ordering, which is sufficient for nearest-neighbor ranking.
+
+/// Squared Euclidean distance over the full slice.
+#[inline(always)]
+pub fn l2_sq(a: &[f32], b: &[f32]) -> f32 {
+    debug_assert_eq!(a.len(), b.len());
+    a.iter()
+        .zip(b.iter())
+        .map(|(x, y)| {
+            let d = x - y;
+            d * d
+        })
+        .sum()
+}
+
+/// Squared Euclidean distance over first `dims` elements only.
+#[inline(always)]
+pub fn l2_sq_partial(a: &[f32], b: &[f32], dims: usize) -> f32 {
+    debug_assert!(dims <= a.len() && dims <= b.len());
+    a[..dims]
+        .iter()
+        .zip(b[..dims].iter())
+        .map(|(x, y)| {
+            let d = x - y;
+            d * d
+        })
+        .sum()
+}
+
+/// Inner product (dot product), returned as f32.
+#[inline(always)]
+pub fn inner_product(a: &[f32], b: &[f32]) -> f32 {
+    debug_assert_eq!(a.len(), b.len());
+    a.iter().zip(b.iter()).map(|(x, y)| x * y).sum()
+}
+
+/// L2 norm of a slice.
+#[inline]
+pub fn l2_norm(v: &[f32]) -> f32 {
+    v.iter().map(|x| x * x).sum::<f32>().sqrt()
+}
+
+/// Normalize a vector in-place to unit L2 norm.
+pub fn normalize(v: &mut [f32]) {
+    let n = l2_norm(v);
+    if n > 1e-9 {
+        for x in v.iter_mut() {
+            *x /= n;
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn l2_sq_identity() {
+        let v = vec![1.0_f32, 2.0, 3.0];
+        assert_eq!(l2_sq(&v, &v), 0.0);
+    }
+
+    #[test]
+    fn l2_sq_known() {
+        let a = vec![0.0_f32, 0.0, 0.0];
+        let b = vec![1.0_f32, 2.0, 2.0];
+        assert!((l2_sq(&a, &b) - 9.0).abs() < 1e-6);
+    }
+
+    #[test]
+    fn l2_sq_partial_prefix() {
+        let a = vec![1.0_f32, 2.0, 100.0];
+        let b = vec![1.0_f32, 2.0, 0.0];
+        assert_eq!(l2_sq_partial(&a, &b, 2), 0.0);
+        assert!((l2_sq(&a, &b) - 10000.0).abs() < 1.0);
+    }
+
+    #[test]
+    fn normalize_unit() {
+        let mut v = vec![3.0_f32, 4.0];
+        normalize(&mut v);
+        assert!((l2_norm(&v) - 1.0).abs() < 1e-6);
+    }
+}

crates/ruvector-dabs/src/error.rs

@@ -0,0 +1,13 @@
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum DabsError {
+    #[error("empty dataset")]
+    EmptyDataset,
+    #[error("dimension mismatch: expected {expected}, got {actual}")]
+    DimMismatch { expected: usize, actual: usize },
+    #[error("k={k} exceeds dataset size n={n}")]
+    KExceedsDataset { k: usize, n: usize },
+    #[error("gamma must be >= 0.0, got {gamma}")]
+    InvalidGamma { gamma: f32 },
+}