ceylon_next/memory/vector/

utils.rs

//! Utility functions for vector operations.

/// Computes the cosine similarity between two vectors.
///
/// Cosine similarity measures the cosine of the angle between two vectors,
/// producing a value between -1.0 and 1.0, where:
/// - 1.0 indicates identical direction (most similar)
/// - 0.0 indicates orthogonal vectors (unrelated)
/// - -1.0 indicates opposite direction (most dissimilar)
///
/// # Arguments
///
/// * `a` - First vector
/// * `b` - Second vector
///
/// # Returns
///
/// The cosine similarity score, or an error if vectors have different dimensions.
///
/// # Example
///
/// ```
/// use ceylon_next::memory::vector::cosine_similarity;
///
/// let v1 = vec![1.0, 2.0, 3.0];
/// let v2 = vec![4.0, 5.0, 6.0];
/// let similarity = cosine_similarity(&v1, &v2).unwrap();
/// ```
pub fn cosine_similarity(a: &[f32], b: &[f32]) -> Result<f32, String> {
    if a.len() != b.len() {
        return Err(format!(
            "Vector dimensions mismatch: {} vs {}",
            a.len(),
            b.len()
        ));
    }

    if a.is_empty() {
        return Err("Cannot compute similarity of empty vectors".to_string());
    }

    let dot_product: f32 = a.iter().zip(b.iter()).map(|(x, y)| x * y).sum();

    let magnitude_a: f32 = a.iter().map(|x| x * x).sum::<f32>().sqrt();
    let magnitude_b: f32 = b.iter().map(|x| x * x).sum::<f32>().sqrt();

    if magnitude_a == 0.0 || magnitude_b == 0.0 {
        return Ok(0.0);
    }

    Ok(dot_product / (magnitude_a * magnitude_b))
}

/// Normalizes a vector to unit length (L2 normalization).
///
/// This scales the vector so that its magnitude (Euclidean norm) is 1.0.
/// Normalized vectors are useful for efficient similarity comparisons.
///
/// # Arguments
///
/// * `vector` - The vector to normalize (will be modified in place)
///
/// # Example
///
/// ```
/// use ceylon_next::memory::vector::normalize_vector;
///
/// let mut v = vec![3.0, 4.0];
/// normalize_vector(&mut v);
/// assert!((v[0] - 0.6).abs() < 0.001);
/// assert!((v[1] - 0.8).abs() < 0.001);
/// ```
pub fn normalize_vector(vector: &mut [f32]) {
    let magnitude: f32 = vector.iter().map(|x| x * x).sum::<f32>().sqrt();

    if magnitude > 0.0 {
        for x in vector.iter_mut() {
            *x /= magnitude;
        }
    }
}

/// Computes the Euclidean distance between two vectors.
///
/// # Arguments
///
/// * `a` - First vector
/// * `b` - Second vector
///
/// # Returns
///
/// The Euclidean distance, or an error if vectors have different dimensions.
pub fn euclidean_distance(a: &[f32], b: &[f32]) -> Result<f32, String> {
    if a.len() != b.len() {
        return Err(format!(
            "Vector dimensions mismatch: {} vs {}",
            a.len(),
            b.len()
        ));
    }

    let sum: f32 = a
        .iter()
        .zip(b.iter())
        .map(|(x, y)| {
            let diff = x - y;
            diff * diff
        })
        .sum();

    Ok(sum.sqrt())
}

/// Computes the dot product of two vectors.
///
/// # Arguments
///
/// * `a` - First vector
/// * `b` - Second vector
///
/// # Returns
///
/// The dot product, or an error if vectors have different dimensions.
pub fn dot_product(a: &[f32], b: &[f32]) -> Result<f32, String> {
    if a.len() != b.len() {
        return Err(format!(
            "Vector dimensions mismatch: {} vs {}",
            a.len(),
            b.len()
        ));
    }

    Ok(a.iter().zip(b.iter()).map(|(x, y)| x * y).sum())
}

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

    #[test]
    fn test_cosine_similarity_identical() {
        let v = vec![1.0, 2.0, 3.0];
        let sim = cosine_similarity(&v, &v).unwrap();
        assert!((sim - 1.0).abs() < 1e-6);
    }

    #[test]
    fn test_cosine_similarity_orthogonal() {
        let v1 = vec![1.0, 0.0];
        let v2 = vec![0.0, 1.0];
        let sim = cosine_similarity(&v1, &v2).unwrap();
        assert!((sim - 0.0).abs() < 1e-6);
    }

    #[test]
    fn test_cosine_similarity_opposite() {
        let v1 = vec![1.0, 0.0];
        let v2 = vec![-1.0, 0.0];
        let sim = cosine_similarity(&v1, &v2).unwrap();
        assert!((sim - (-1.0)).abs() < 1e-6);
    }

    #[test]
    fn test_normalize_vector() {
        let mut v = vec![3.0, 4.0];
        normalize_vector(&mut v);
        assert!((v[0] - 0.6).abs() < 1e-6);
        assert!((v[1] - 0.8).abs() < 1e-6);

        // Check magnitude is 1.0
        let magnitude: f32 = v.iter().map(|x| x * x).sum::<f32>().sqrt();
        assert!((magnitude - 1.0).abs() < 1e-6);
    }

    #[test]
    fn test_euclidean_distance() {
        let v1 = vec![1.0, 2.0];
        let v2 = vec![4.0, 6.0];
        let dist = euclidean_distance(&v1, &v2).unwrap();
        assert!((dist - 5.0).abs() < 1e-6);
    }

    #[test]
    fn test_dot_product() {
        let v1 = vec![1.0, 2.0, 3.0];
        let v2 = vec![4.0, 5.0, 6.0];
        let dot = dot_product(&v1, &v2).unwrap();
        assert!((dot - 32.0).abs() < 1e-6); // 1*4 + 2*5 + 3*6 = 32
    }

    #[test]
    fn test_dimension_mismatch() {
        let v1 = vec![1.0, 2.0];
        let v2 = vec![1.0, 2.0, 3.0];
        assert!(cosine_similarity(&v1, &v2).is_err());
        assert!(euclidean_distance(&v1, &v2).is_err());
        assert!(dot_product(&v1, &v2).is_err());
    }
}