Skip to content

armgit / ente

Public Imported from GitHub
0

πŸ’š End-to-end encrypted cloud for everything.

vecdb: add SIMD distance kernel and chunked vector arena

laurensprieme18dddd71b18
diff --git a/rust/crates/ml/src/lib.rs b/rust/crates/ml/src/lib.rs
index d81b1b88d5..32a7d281f1 100644
--- a/rust/crates/ml/src/lib.rs
+++ b/rust/crates/ml/src/lib.rs
@@ -15,6 +15,6 @@ mod preprocess;
mod runtime;
pub mod scan;
pub mod types;
+pub mod vecdb;
#[cfg(feature = "usearch")]
pub mod vector_db;
-pub mod vecdb;
diff --git a/rust/crates/ml/src/vecdb/arena.rs b/rust/crates/ml/src/vecdb/arena.rs
index e69de29bb2..8a69f2d451 100644
--- a/rust/crates/ml/src/vecdb/arena.rs
+++ b/rust/crates/ml/src/vecdb/arena.rs
@@ -0,0 +1,509 @@
+#![allow(dead_code)]
+
+use std::collections::HashMap;
+
+use wide::f32x8;
+
+use super::VecDbError;
+use super::kernel::{
+ F32Kernel, LANE_WIDTH, VectorKernel, pack_lanes, pack_lanes_into, unpack_lanes,
+};
+
+pub(crate) const VECTORS_PER_CHUNK: usize = 4096;
+pub(crate) const MAX_KEY_BYTES: usize = 256;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum UpsertOutcome {
+ NewSlot(u32),
+ RecycledSlot(u32),
+ ReplacedInPlace(u32),
+}
+
+impl UpsertOutcome {
+ pub(crate) fn slot(self) -> u32 {
+ match self {
+ UpsertOutcome::NewSlot(slot)
+ | UpsertOutcome::RecycledSlot(slot)
+ | UpsertOutcome::ReplacedInPlace(slot) => slot,
+ }
+ }
+}
+
+pub(crate) fn validate_key(key: &str) -> Result<(), VecDbError> {
+ if key.is_empty() {
+ return Err(VecDbError::InvalidKey("key is empty".to_string()));
+ }
+ if key.len() > MAX_KEY_BYTES {
+ return Err(VecDbError::InvalidKey(format!(
+ "key is {} bytes, limit is {MAX_KEY_BYTES}",
+ key.len()
+ )));
+ }
+ Ok(())
+}
+
+pub(crate) struct VectorArena {
+ dims: usize,
+ lanes_per_vector: usize,
+ chunks: Vec<Vec<f32x8>>,
+ keys_to_slots: HashMap<Box<str>, u32>,
+ slots_to_keys: Vec<Box<str>>,
+ alive: Vec<u64>,
+ free_slots: Vec<u32>,
+ live_count: usize,
+}
+
+impl VectorArena {
+ pub(crate) fn new(dims: usize) -> Result<Self, VecDbError> {
+ if dims == 0 || !dims.is_multiple_of(LANE_WIDTH) {
+ return Err(VecDbError::InvalidDimensions(dims));
+ }
+ Ok(Self {
+ dims,
+ lanes_per_vector: dims / LANE_WIDTH,
+ chunks: Vec::new(),
+ keys_to_slots: HashMap::new(),
+ slots_to_keys: Vec::new(),
+ alive: Vec::new(),
+ free_slots: Vec::new(),
+ live_count: 0,
+ })
+ }
+
+ pub(crate) fn dims(&self) -> usize {
+ self.dims
+ }
+
+ pub(crate) fn live_count(&self) -> usize {
+ self.live_count
+ }
+
+ pub(crate) fn dead_count(&self) -> usize {
+ self.free_slots.len()
+ }
+
+ pub(crate) fn slot_count(&self) -> usize {
+ self.slots_to_keys.len()
+ }
+
+ pub(crate) fn is_empty(&self) -> bool {
+ self.live_count == 0
+ }
+
+ pub(crate) fn upsert(
+ &mut self,
+ key: &str,
+ vector: &[f32],
+ ) -> Result<UpsertOutcome, VecDbError> {
+ validate_key(key)?;
+ if vector.len() != self.dims {
+ return Err(VecDbError::DimensionMismatch {
+ expected: self.dims,
+ actual: vector.len(),
+ });
+ }
+ if let Some(&slot) = self.keys_to_slots.get(key) {
+ self.write_vector(slot, vector);
+ return Ok(UpsertOutcome::ReplacedInPlace(slot));
+ }
+ if let Some(slot) = self.free_slots.pop() {
+ self.slots_to_keys[slot as usize] = Box::from(key);
+ self.keys_to_slots.insert(Box::from(key), slot);
+ self.mark_alive(slot);
+ self.live_count += 1;
+ self.write_vector(slot, vector);
+ return Ok(UpsertOutcome::RecycledSlot(slot));
+ }
+ let slot = self.slots_to_keys.len() as u32;
+ if slot as usize == self.chunks.len() * VECTORS_PER_CHUNK {
+ self.chunks
+ .push(vec![f32x8::ZERO; VECTORS_PER_CHUNK * self.lanes_per_vector]);
+ }
+ if slot as usize / 64 == self.alive.len() {
+ self.alive.push(0);
+ }
+ self.slots_to_keys.push(Box::from(key));
+ self.keys_to_slots.insert(Box::from(key), slot);
+ self.mark_alive(slot);
+ self.live_count += 1;
+ self.write_vector(slot, vector);
+ Ok(UpsertOutcome::NewSlot(slot))
+ }
+
+ pub(crate) fn remove(&mut self, key: &str) -> Option<u32> {
+ let slot = self.keys_to_slots.remove(key)?;
+ self.mark_dead(slot);
+ self.live_count -= 1;
+ self.free_slots.push(slot);
+ Some(slot)
+ }
+
+ pub(crate) fn slot_of_key(&self, key: &str) -> Option<u32> {
+ self.keys_to_slots.get(key).copied()
+ }
+
+ pub(crate) fn key_of_slot(&self, slot: u32) -> Option<&str> {
+ if self.is_alive(slot) {
+ Some(&self.slots_to_keys[slot as usize])
+ } else {
+ None
+ }
+ }
+
+ pub(crate) fn is_alive(&self, slot: u32) -> bool {
+ self.alive
+ .get(slot as usize / 64)
+ .is_some_and(|word| word & (1u64 << (slot % 64)) != 0)
+ }
+
+ pub(crate) fn live_slots(&self) -> impl Iterator<Item = u32> {
+ (0..self.slots_to_keys.len() as u32).filter(|slot| self.is_alive(*slot))
+ }
+
+ pub(crate) fn vector_lanes(&self, slot: u32) -> &[f32x8] {
+ let start = (slot as usize % VECTORS_PER_CHUNK) * self.lanes_per_vector;
+ &self.chunks[slot as usize / VECTORS_PER_CHUNK][start..start + self.lanes_per_vector]
+ }
+
+ pub(crate) fn vector_values(&self, slot: u32) -> Vec<f32> {
+ unpack_lanes(self.vector_lanes(slot))
+ }
+
+ pub(crate) fn pack_query(&self, values: &[f32]) -> Result<Vec<f32x8>, VecDbError> {
+ if values.len() != self.dims {
+ return Err(VecDbError::DimensionMismatch {
+ expected: self.dims,
+ actual: values.len(),
+ });
+ }
+ Ok(pack_lanes(values))
+ }
+
+ pub(crate) fn distance_between_slots(&self, a: u32, b: u32) -> f32 {
+ F32Kernel::distance(self.vector_lanes(a), self.vector_lanes(b))
+ }
+
+ pub(crate) fn distance_to_query(&self, query: &[f32x8], slot: u32) -> f32 {
+ F32Kernel::distance(query, self.vector_lanes(slot))
+ }
+
+ fn vector_lanes_mut(&mut self, slot: u32) -> &mut [f32x8] {
+ let start = (slot as usize % VECTORS_PER_CHUNK) * self.lanes_per_vector;
+ &mut self.chunks[slot as usize / VECTORS_PER_CHUNK][start..start + self.lanes_per_vector]
+ }
+
+ fn write_vector(&mut self, slot: u32, values: &[f32]) {
+ pack_lanes_into(values, self.vector_lanes_mut(slot));
+ }
+
+ fn mark_alive(&mut self, slot: u32) {
+ self.alive[slot as usize / 64] |= 1u64 << (slot % 64);
+ }
+
+ fn mark_dead(&mut self, slot: u32) {
+ self.alive[slot as usize / 64] &= !(1u64 << (slot % 64));
+ }
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn splitmix64(state: &mut u64) -> u64 {
+ *state = state.wrapping_add(0x9E37_79B9_7F4A_7C15);
+ let mut z = *state;
+ z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
+ z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
+ z ^ (z >> 31)
+ }
+
+ fn seeded_vector(seed: u64, dims: usize) -> Vec<f32> {
+ let mut state = seed;
+ (0..dims)
+ .map(|_| {
+ let unit = (splitmix64(&mut state) >> 40) as f32 / (1u64 << 24) as f32;
+ unit * 2.0 - 1.0
+ })
+ .collect()
+ }
+
+ fn basis_vector(dims: usize, axis: usize) -> Vec<f32> {
+ let mut values = vec![0.0; dims];
+ values[axis] = 1.0;
+ values
+ }
+
+ fn arena_with_keys(dims: usize, keys: &[&str]) -> VectorArena {
+ let mut arena = VectorArena::new(dims).unwrap();
+ for (index, key) in keys.iter().enumerate() {
+ arena
+ .upsert(key, &seeded_vector(index as u64, dims))
+ .unwrap();
+ }
+ arena
+ }
+
+ #[test]
+ fn rejects_invalid_dimensions() {
+ assert!(matches!(
+ VectorArena::new(0),
+ Err(VecDbError::InvalidDimensions(0))
+ ));
+ assert!(matches!(
+ VectorArena::new(12),
+ Err(VecDbError::InvalidDimensions(12))
+ ));
+ assert!(VectorArena::new(8).is_ok());
+ assert!(VectorArena::new(512).is_ok());
+ }
+
+ #[test]
+ fn rejects_invalid_keys() {
+ let mut arena = VectorArena::new(8).unwrap();
+ let vector = seeded_vector(1, 8);
+ assert!(matches!(
+ arena.upsert("", &vector),
+ Err(VecDbError::InvalidKey(_))
+ ));
+ let at_limit = "k".repeat(256);
+ assert!(arena.upsert(&at_limit, &vector).is_ok());
+ let over_limit = "k".repeat(257);
+ assert!(matches!(
+ arena.upsert(&over_limit, &vector),
+ Err(VecDbError::InvalidKey(_))
+ ));
+ let multibyte_over_limit = format!("{}Γ©", "k".repeat(255));
+ assert_eq!(multibyte_over_limit.len(), 257);
+ assert!(matches!(
+ arena.upsert(&multibyte_over_limit, &vector),
+ Err(VecDbError::InvalidKey(_))
+ ));
+ }
+
+ #[test]
+ fn rejects_dimension_mismatch() {
+ let mut arena = VectorArena::new(16).unwrap();
+ assert!(matches!(
+ arena.upsert("key", &seeded_vector(1, 8)),
+ Err(VecDbError::DimensionMismatch {
+ expected: 16,
+ actual: 8
+ })
+ ));
+ assert!(matches!(
+ arena.pack_query(&seeded_vector(1, 24)),
+ Err(VecDbError::DimensionMismatch {
+ expected: 16,
+ actual: 24
+ })
+ ));
+ }
+
+ #[test]
+ fn assigns_slots_in_encounter_order() {
+ let arena = arena_with_keys(8, &["a", "b", "c"]);
+ assert_eq!(arena.slot_of_key("a"), Some(0));
+ assert_eq!(arena.slot_of_key("b"), Some(1));
+ assert_eq!(arena.slot_of_key("c"), Some(2));
+ }
+
+ #[test]
+ fn upsert_replaces_in_place() {
+ let mut arena = VectorArena::new(8).unwrap();
+ let first = seeded_vector(1, 8);
+ let second = seeded_vector(2, 8);
+ assert_eq!(
+ arena.upsert("key", &first).unwrap(),
+ UpsertOutcome::NewSlot(0)
+ );
+ assert_eq!(
+ arena.upsert("key", &second).unwrap(),
+ UpsertOutcome::ReplacedInPlace(0)
+ );
+ assert_eq!(arena.vector_values(0), second);
+ assert_eq!(arena.live_count(), 1);
+ assert_eq!(arena.slot_count(), 1);
+ }
+
+ #[test]
+ fn free_list_reuses_most_recently_freed_slot_first() {
+ let mut arena = arena_with_keys(8, &["a", "b", "c"]);
+ assert_eq!(arena.remove("a"), Some(0));
+ assert_eq!(arena.remove("c"), Some(2));
+ assert_eq!(
+ arena.upsert("d", &seeded_vector(4, 8)).unwrap(),
+ UpsertOutcome::RecycledSlot(2)
+ );
+ assert_eq!(
+ arena.upsert("e", &seeded_vector(5, 8)).unwrap(),
+ UpsertOutcome::RecycledSlot(0)
+ );
+ assert_eq!(
+ arena.upsert("f", &seeded_vector(6, 8)).unwrap(),
+ UpsertOutcome::NewSlot(3)
+ );
+ }
+
+ #[test]
+ fn remove_is_noop_for_absent_key() {
+ let mut arena = arena_with_keys(8, &["a"]);
+ assert_eq!(arena.remove("missing"), None);
+ assert_eq!(arena.remove("a"), Some(0));
+ assert_eq!(arena.remove("a"), None);
+ }
+
+ #[test]
+ fn lookups_work_in_both_directions() {
+ let mut arena = arena_with_keys(8, &["a", "b"]);
+ assert_eq!(arena.slot_of_key("b"), Some(1));
+ assert_eq!(arena.key_of_slot(1), Some("b"));
+ assert!(arena.is_alive(1));
+ arena.remove("b");
+ assert_eq!(arena.slot_of_key("b"), None);
+ assert_eq!(arena.key_of_slot(1), None);
+ assert!(!arena.is_alive(1));
+ assert_eq!(arena.key_of_slot(999), None);
+ assert!(!arena.is_alive(999));
+ }
+
+ #[test]
+ fn tracks_live_and_dead_counts() {
+ let mut arena = arena_with_keys(8, &["a", "b", "c"]);
+ assert_eq!(arena.live_count(), 3);
+ assert_eq!(arena.dead_count(), 0);
+ assert!(!arena.is_empty());
+ arena.remove("b");
+ assert_eq!(arena.live_count(), 2);
+ assert_eq!(arena.dead_count(), 1);
+ arena.upsert("d", &seeded_vector(9, 8)).unwrap();
+ assert_eq!(arena.live_count(), 3);
+ assert_eq!(arena.dead_count(), 0);
+ assert_eq!(arena.live_slots().collect::<Vec<_>>(), vec![0, 1, 2]);
+ }
+
+ #[test]
+ fn dead_slot_vectors_stay_readable_for_routing() {
+ let mut arena = VectorArena::new(8).unwrap();
+ let vector = seeded_vector(3, 8);
+ arena.upsert("a", &vector).unwrap();
+ arena.remove("a");
+ assert_eq!(arena.vector_values(0), vector);
+ }
+
+ #[test]
+ fn readding_a_removed_key_recycles_like_any_new_key() {
+ let mut arena = arena_with_keys(8, &["a", "b"]);
+ assert_eq!(arena.remove("a"), Some(0));
+ let vector = seeded_vector(9, 8);
+ assert_eq!(
+ arena.upsert("a", &vector).unwrap(),
+ UpsertOutcome::RecycledSlot(0)
+ );
+ assert_eq!(arena.key_of_slot(0), Some("a"));
+ assert_eq!(arena.vector_values(0), vector);
+ assert_eq!(arena.live_count(), 2);
+ assert_eq!(arena.dead_count(), 0);
+ assert_eq!(arena.remove("b"), Some(1));
+ assert_eq!(
+ arena.upsert("c", &seeded_vector(10, 8)).unwrap(),
+ UpsertOutcome::RecycledSlot(1)
+ );
+ assert_eq!(
+ arena.upsert("b", &seeded_vector(11, 8)).unwrap(),
+ UpsertOutcome::NewSlot(2)
+ );
+ }
+
+ #[test]
+ fn identical_operation_sequences_assign_identical_slots() {
+ let mut first = VectorArena::new(8).unwrap();
+ let mut second = VectorArena::new(8).unwrap();
+ let mut state = 42u64;
+ let mut keys: Vec<String> = Vec::new();
+ let mut removed: Vec<String> = Vec::new();
+ let mut operations = Vec::new();
+ for step in 0..2000 {
+ let roll = splitmix64(&mut state);
+ match roll % 4 {
+ 0 if !keys.is_empty() => {
+ let key = keys.remove(roll as usize % keys.len());
+ removed.push(key.clone());
+ operations.push((key, None));
+ }
+ 1 if !removed.is_empty() => {
+ let key = removed.remove(roll as usize % removed.len());
+ keys.push(key.clone());
+ operations.push((key, Some(seeded_vector(roll, 8))));
+ }
+ _ => {
+ let key = format!("key-{step}");
+ keys.push(key.clone());
+ operations.push((key, Some(seeded_vector(roll, 8))));
+ }
+ }
+ }
+ for (key, vector) in &operations {
+ match vector {
+ Some(values) => {
+ let a = first.upsert(key, values).unwrap();
+ let b = second.upsert(key, values).unwrap();
+ assert_eq!(a, b);
+ }
+ None => assert_eq!(first.remove(key), second.remove(key)),
+ }
+ }
+ assert_eq!(first.live_count(), second.live_count());
+ assert_eq!(first.slot_count(), second.slot_count());
+ for slot in first.live_slots() {
+ assert_eq!(first.key_of_slot(slot), second.key_of_slot(slot));
+ assert_eq!(first.vector_values(slot), second.vector_values(slot));
+ }
+ }
+
+ #[test]
+ fn grows_across_chunks_without_moving_existing_vectors() {
+ let mut arena = VectorArena::new(8).unwrap();
+ arena.upsert("key-0", &seeded_vector(0, 8)).unwrap();
+ let first_vector_address = arena.vector_lanes(0).as_ptr() as usize;
+ for index in 1..4100u64 {
+ arena
+ .upsert(&format!("key-{index}"), &seeded_vector(index, 8))
+ .unwrap();
+ }
+ assert_eq!(arena.slot_count(), 4100);
+ assert_eq!(arena.live_count(), 4100);
+ assert_eq!(arena.chunks.len(), 2);
+ assert_eq!(
+ arena.vector_lanes(0).as_ptr() as usize,
+ first_vector_address
+ );
+ assert_eq!(arena.slot_of_key("key-4099"), Some(4099));
+ assert_eq!(arena.key_of_slot(4097), Some("key-4097"));
+ assert_eq!(arena.vector_values(4099), seeded_vector(4099, 8));
+ }
+
+ #[test]
+ fn every_slotted_vector_is_32_byte_aligned() {
+ let mut arena = VectorArena::new(16).unwrap();
+ for index in 0..4200u64 {
+ arena
+ .upsert(&format!("key-{index}"), &seeded_vector(index, 16))
+ .unwrap();
+ }
+ for slot in arena.live_slots() {
+ assert_eq!(arena.vector_lanes(slot).as_ptr() as usize % 32, 0);
+ }
+ }
+
+ #[test]
+ fn distances_use_the_kernel_metric() {
+ let mut arena = VectorArena::new(16).unwrap();
+ arena.upsert("x", &basis_vector(16, 0)).unwrap();
+ arena.upsert("y", &basis_vector(16, 9)).unwrap();
+ assert_eq!(arena.distance_between_slots(0, 0), 0.0);
+ assert_eq!(arena.distance_between_slots(0, 1), 1.0);
+ let query = arena.pack_query(&basis_vector(16, 0)).unwrap();
+ assert_eq!(arena.distance_to_query(&query, 0), 0.0);
+ assert_eq!(arena.distance_to_query(&query, 1), 1.0);
+ }
+}
diff --git a/rust/crates/ml/src/vecdb/graph.rs b/rust/crates/ml/src/vecdb/graph.rs
index e69de29bb2..8b13789179 100644
--- a/rust/crates/ml/src/vecdb/graph.rs
+++ b/rust/crates/ml/src/vecdb/graph.rs
@@ -0,0 +1 @@
+
diff --git a/rust/crates/ml/src/vecdb/kernel.rs b/rust/crates/ml/src/vecdb/kernel.rs
index e69de29bb2..8be915152f 100644
--- a/rust/crates/ml/src/vecdb/kernel.rs
+++ b/rust/crates/ml/src/vecdb/kernel.rs
@@ -0,0 +1,159 @@
+#![allow(dead_code)]
+
+use wide::f32x8;
+
+pub(crate) const LANE_WIDTH: usize = 8;
+
+pub(crate) trait VectorKernel {
+ type Lane;
+
+ fn dot(a: &[Self::Lane], b: &[Self::Lane]) -> f32;
+
+ fn distance(a: &[Self::Lane], b: &[Self::Lane]) -> f32 {
+ 1.0 - Self::dot(a, b)
+ }
+}
+
+pub(crate) struct F32Kernel;
+
+impl VectorKernel for F32Kernel {
+ type Lane = f32x8;
+
+ fn dot(a: &[f32x8], b: &[f32x8]) -> f32 {
+ debug_assert_eq!(a.len(), b.len());
+ let mut acc = f32x8::ZERO;
+ for (x, y) in a.iter().zip(b.iter()) {
+ acc += *x * *y;
+ }
+ acc.to_array().iter().sum()
+ }
+}
+
+pub(crate) fn pack_lanes(values: &[f32]) -> Vec<f32x8> {
+ debug_assert_eq!(values.len() % LANE_WIDTH, 0);
+ let mut lanes = vec![f32x8::ZERO; values.len() / LANE_WIDTH];
+ pack_lanes_into(values, &mut lanes);
+ lanes
+}
+
+pub(crate) fn pack_lanes_into(values: &[f32], lanes: &mut [f32x8]) {
+ debug_assert_eq!(values.len(), lanes.len() * LANE_WIDTH);
+ let (groups, remainder) = values.as_chunks::<LANE_WIDTH>();
+ debug_assert!(remainder.is_empty());
+ for (lane, group) in lanes.iter_mut().zip(groups) {
+ *lane = f32x8::from(*group);
+ }
+}
+
+pub(crate) fn unpack_lanes(lanes: &[f32x8]) -> Vec<f32> {
+ let mut values = Vec::with_capacity(lanes.len() * LANE_WIDTH);
+ for lane in lanes {
+ values.extend_from_slice(&lane.to_array());
+ }
+ values
+}
+
+#[cfg(test)]
+mod tests {
+ use super::*;
+
+ fn splitmix64(state: &mut u64) -> u64 {
+ *state = state.wrapping_add(0x9E37_79B9_7F4A_7C15);
+ let mut z = *state;
+ z = (z ^ (z >> 30)).wrapping_mul(0xBF58_476D_1CE4_E5B9);
+ z = (z ^ (z >> 27)).wrapping_mul(0x94D0_49BB_1331_11EB);
+ z ^ (z >> 31)
+ }
+
+ fn seeded_values(seed: u64, count: usize) -> Vec<f32> {
+ let mut state = seed;
+ (0..count)
+ .map(|index| {
+ let unit = (splitmix64(&mut state) >> 40) as f32 / (1u64 << 24) as f32;
+ let signed = unit * 2.0 - 1.0;
+ match index % 5 {
+ 0 => signed * 1.0e6,
+ 1 => signed * 1.0e-6,
+ _ => signed,
+ }
+ })
+ .collect()
+ }
+
+ fn reference_dot(a: &[f32], b: &[f32]) -> f32 {
+ let mut partials = [0.0f32; LANE_WIDTH];
+ for (index, (x, y)) in a.iter().zip(b).enumerate() {
+ partials[index % LANE_WIDTH] += x * y;
+ }
+ partials.iter().sum()
+ }
+
+ fn basis_vector(dims: usize, axis: usize) -> Vec<f32> {
+ let mut values = vec![0.0; dims];
+ values[axis] = 1.0;
+ values
+ }
+
+ #[test]
+ fn dot_matches_scalar_reference_bit_exactly() {
+ for (dims, seed) in [(128, 11), (192, 22), (512, 33)] {
+ let a = seeded_values(seed, dims);
+ let b = seeded_values(seed.wrapping_mul(977), dims);
+ let simd = F32Kernel::dot(&pack_lanes(&a), &pack_lanes(&b));
+ let reference = reference_dot(&a, &b);
+ assert!(reference.is_finite());
+ assert_ne!(reference, 0.0);
+ assert_eq!(simd.to_bits(), reference.to_bits());
+ }
+ }
+
+ #[test]
+ fn dot_handles_negative_values() {
+ let a: Vec<f32> = (0..128)
+ .map(|i| if i % 2 == 0 { -1.5 } else { 2.0 })
+ .collect();
+ let b: Vec<f32> = (0..128)
+ .map(|i| if i % 3 == 0 { 0.25 } else { -4.0 })
+ .collect();
+ let simd = F32Kernel::dot(&pack_lanes(&a), &pack_lanes(&b));
+ assert_eq!(simd.to_bits(), reference_dot(&a, &b).to_bits());
+ }
+
+ #[test]
+ fn distance_is_one_minus_dot() {
+ let a = seeded_values(7, 192);
+ let b = seeded_values(13, 192);
+ let lanes_a = pack_lanes(&a);
+ let lanes_b = pack_lanes(&b);
+ let expected = 1.0 - F32Kernel::dot(&lanes_a, &lanes_b);
+ assert_eq!(
+ F32Kernel::distance(&lanes_a, &lanes_b).to_bits(),
+ expected.to_bits()
+ );
+ }
+
+ #[test]
+ fn distance_of_basis_vectors_is_exact() {
+ let e0 = pack_lanes(&basis_vector(128, 0));
+ let e1 = pack_lanes(&basis_vector(128, 100));
+ assert_eq!(F32Kernel::distance(&e0, &e0), 0.0);
+ assert_eq!(F32Kernel::distance(&e0, &e1), 1.0);
+ }
+
+ #[test]
+ fn pack_unpack_round_trips() {
+ let values = seeded_values(99, 512);
+ let lanes = pack_lanes(&values);
+ assert_eq!(lanes.len(), 64);
+ assert_eq!(unpack_lanes(&lanes), values);
+ }
+
+ #[test]
+ fn packed_lanes_are_32_byte_aligned() {
+ assert_eq!(align_of::<f32x8>(), 32);
+ for dims in [128, 192, 512] {
+ let lanes = pack_lanes(&seeded_values(5, dims));
+ assert_eq!(lanes.as_ptr() as usize % 32, 0);
+ }
+ }
+}
diff --git a/rust/crates/ml/src/vecdb/lock.rs b/rust/crates/ml/src/vecdb/lock.rs
index e69de29bb2..8b13789179 100644
--- a/rust/crates/ml/src/vecdb/lock.rs
+++ b/rust/crates/ml/src/vecdb/lock.rs
@@ -0,0 +1 @@
+
diff --git a/rust/crates/ml/src/vecdb/log.rs b/rust/crates/ml/src/vecdb/log.rs
index e69de29bb2..8b13789179 100644
--- a/rust/crates/ml/src/vecdb/log.rs
+++ b/rust/crates/ml/src/vecdb/log.rs
@@ -0,0 +1 @@
+
diff --git a/rust/crates/ml/src/vecdb/mod.rs b/rust/crates/ml/src/vecdb/mod.rs
index 1ef5e67c64..592144423b 100644
--- a/rust/crates/ml/src/vecdb/mod.rs
+++ b/rust/crates/ml/src/vecdb/mod.rs
@@ -1,3 +1,7 @@
+use std::path::PathBuf;
+
+use thiserror::Error;
+
mod arena;
mod graph;
mod kernel;
@@ -5,3 +9,27 @@ mod lock;
mod log;
mod snapshot;
mod store;
+
+#[derive(Debug, Error)]
+pub enum VecDbError {
+ #[error("{}: {source}", path.display())]
+ Io {
+ path: PathBuf,
+ #[source]
+ source: std::io::Error,
+ },
+ #[error("corrupt vector db: {0}")]
+ Corrupt(String),
+ #[error("{}: locked by another writer", .0.display())]
+ Locked(PathBuf),
+ #[error("vector db was opened read-only")]
+ ReadOnly,
+ #[error("invalid key: {0}")]
+ InvalidKey(String),
+ #[error("dimension mismatch: expected {expected}, got {actual}")]
+ DimensionMismatch { expected: usize, actual: usize },
+ #[error("invalid dimensions {0}: must be a nonzero multiple of 8")]
+ InvalidDimensions(usize),
+ #[error("search requires a limit or a max distance")]
+ UnboundedSearch,
+}
diff --git a/rust/crates/ml/src/vecdb/snapshot.rs b/rust/crates/ml/src/vecdb/snapshot.rs
index e69de29bb2..8b13789179 100644
--- a/rust/crates/ml/src/vecdb/snapshot.rs
+++ b/rust/crates/ml/src/vecdb/snapshot.rs
@@ -0,0 +1 @@
+
diff --git a/rust/crates/ml/src/vecdb/store.rs b/rust/crates/ml/src/vecdb/store.rs
index e69de29bb2..8b13789179 100644
--- a/rust/crates/ml/src/vecdb/store.rs
+++ b/rust/crates/ml/src/vecdb/store.rs
@@ -0,0 +1 @@
+