Vector Library

A high-performance vector operations library providing distance metrics, data types, and utilities for vector computations in Rust.

Overview

The Vector library provides essential functionality for vector operations, including distance metrics, data types, and utilities used by the DiskANN project. It's designed for high-performance vector computations with support for different numeric types and distance functions.

Features

• Multiple distance metrics - L2, cosine, hamming and more
• Flexible data types - Support for f32, f16, and other numeric types
• High performance - Optimized vector operations
• Type safety - Strong typing for vector dimensions
• SIMD support - Vectorized operations where available
• Cross-platform - Works on multiple architectures

Distance Metrics

L2 Distance (Euclidean)

use diskann_vector::{Metric, distance::FullPrecisionDistance};

let v1 = [1.0f32, 2.0, 3.0];
let v2 = [4.0f32, 5.0, 6.0];

let d = <[f32; 3] as FullPrecisionDistance<f32, 3>>::distance_compare(&v1, &v2, Metric::L2);
// Calculates: sqrt((4-1)² + (5-2)² + (6-3)²)

Cosine Distance

let v1 = [1.0, 2.0, 3.0];
let v2 = [4.0, 5.0, 6.0];

let d_cos = <[f32; 3] as FullPrecisionDistance<f32, 3>>
    ::distance_compare(&v1, &v2, Metric::Cosine);

hamming distance

let a: [u32; 4] = [0,1,2,3];
let b: [u32; 4] = [0,1,5,3];
let d = <[u32; 4] as FullPrecisionDistance<u32, 4>>::distance_compare(&a, &b, Metric::Hamming);

Data Types

Supported Types

• f32 - 32-bit floating point (most common)

• f16 - 16-bit floating point (memory efficient)

• f64 - 64-bit floating point (high precision)

Advanced Usage

Custom Distance Metrics

use vector::{FullPrecisionDistance, Metric};

// Implement custom distance for your type
impl FullPrecisionDistance<f32, 128> for [f32; 128] {
    fn l2_distance(&self, other: &[f32; 128]) -> f32 {
        self.iter()
            .zip(other.iter())
            .map(|(a, b)| (a - b).powi(2))
            .sum::<f32>()
            .sqrt()
    }
}

Integration with DiskANN

The Vector library is designed to work seamlessly with DiskANN:

use diskann::{IndexBuilder, Metric};
use diskann_vector::FullPrecisionDistance;

// Create index with vector types
let mut index = IndexBuilder::new()
    .with_dimension(128)
    .with_metric(Metric::L2)
    .build_in_memory::<f32>()?;

// Insert vectors
let vectors: Vec<[f32; 128]> = vec![/* your vectors */];
index.insert_batch(&vectors)?;

Benchmarks

Performance comparison of different distance metrics (Intel i7-8700K):

Times are per vector pair comparison

Development

Building

cargo build --release

Testing

cargo test

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

We welcome contributions! Please see the main README for contribution guidelines.