minimemory 3.0.0

Embedded vector database library for Rust - like SQLite for vectors
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105

mod simd;

use serde::{Deserialize, Serialize};

/// Métricas de distancia para similitud vectorial.
///
/// Todas las métricas retornan valores donde **menor = más similar**.
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq)]
pub enum Distance {
    /// Distancia coseno (1 - similitud_coseno)
    /// - 0 = vectores idénticos
    /// - 1 = vectores ortogonales
    /// - 2 = vectores opuestos
    Cosine,
    /// Distancia euclidiana (L2)
    /// - 0 = vectores idénticos
    /// - Rango: [0, ∞)
    Euclidean,
    /// Producto punto negativo
    /// - Valores más negativos = más similares
    DotProduct,
    /// Distancia Manhattan (L1)
    /// - Suma de diferencias absolutas
    /// - 0 = vectores idénticos
    /// - Rango: [0, ∞)
    Manhattan,
}

impl Distance {
    /// Calcula la distancia entre dos vectores.
    ///
    /// Usa implementaciones SIMD (AVX2/SSE) cuando están disponibles
    /// para máximo rendimiento.
    #[inline]
    pub fn calculate(&self, a: &[f32], b: &[f32]) -> f32 {
        match self {
            Distance::Cosine => simd::cosine_distance(a, b),
            Distance::Euclidean => simd::euclidean_distance(a, b),
            Distance::DotProduct => simd::dot_product_distance(a, b),
            Distance::Manhattan => simd::manhattan_distance(a, b),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_cosine_identical_vectors() {
        let a = vec![1.0, 2.0, 3.0];
        let b = vec![1.0, 2.0, 3.0];
        let dist = Distance::Cosine.calculate(&a, &b);
        assert!((dist - 0.0).abs() < 1e-6);
    }

    #[test]
    fn test_cosine_orthogonal_vectors() {
        let a = vec![1.0, 0.0];
        let b = vec![0.0, 1.0];
        let dist = Distance::Cosine.calculate(&a, &b);
        assert!((dist - 1.0).abs() < 1e-6);
    }

    #[test]
    fn test_euclidean_identical_vectors() {
        let a = vec![1.0, 2.0, 3.0];
        let b = vec![1.0, 2.0, 3.0];
        let dist = Distance::Euclidean.calculate(&a, &b);
        assert!((dist - 0.0).abs() < 1e-6);
    }

    #[test]
    fn test_euclidean_known_distance() {
        let a = vec![0.0, 0.0];
        let b = vec![3.0, 4.0];
        let dist = Distance::Euclidean.calculate(&a, &b);
        assert!((dist - 5.0).abs() < 1e-6);
    }

    #[test]
    fn test_manhattan_identical_vectors() {
        let a = vec![1.0, 2.0, 3.0];
        let b = vec![1.0, 2.0, 3.0];
        let dist = Distance::Manhattan.calculate(&a, &b);
        assert!((dist - 0.0).abs() < 1e-6);
    }

    #[test]
    fn test_manhattan_known_distance() {
        let a = vec![0.0, 0.0];
        let b = vec![3.0, 4.0];
        let dist = Distance::Manhattan.calculate(&a, &b);
        assert!((dist - 7.0).abs() < 1e-6); // |3| + |4| = 7
    }

    #[test]
    fn test_dot_product() {
        let a = vec![1.0, 2.0, 3.0];
        let b = vec![4.0, 5.0, 6.0];
        let dist = Distance::DotProduct.calculate(&a, &b);
        // dot = 1*4 + 2*5 + 3*6 = 32, distance = -32
        assert!((dist - (-32.0)).abs() < 1e-6);
    }
}