How to Use SIMD Optimizations (AVX-512, AVX2, NEON, WASM SIMD128) in VelesDB

VelesDB automatically dispatches vector-space operations to the optimal SIMD implementation—whether AVX-512 on x86_64, NEON on ARM64, or SIMD128 on WebAssembly—based on runtime CPU feature detection, requiring no manual configuration.

VelesDB is an open-source vector database that accelerates similarity search through hardware-specific SIMD intrinsics. The cyberlife-coder/velesdb repository provides native Rust implementations for multiple architectures, ensuring high-performance dot products, Euclidean distances, and cosine similarity calculations across x86, ARM, and WASM targets.

SIMD Architecture Overview in VelesDB

VelesDB organizes its SIMD layer into architecture-specific modules that are selected at compile time and dispatched at runtime. The system supports four primary SIMD flavors, each isolated in dedicated source files to maintain clean cross-platform builds.

x86_64 Implementations (AVX-512 and AVX2)

For Intel and AMD processors, VelesDB leverages the simd_native module located in crates/velesdb-core/src/simd_native/. This module wraps Rust intrinsics for AVX-512F, AVX2, and POPCNT instructions. The dispatch logic in simd_native/dispatch/mod.rs selects between scalar, 4-wide, 8-wide, and AVX-512 code paths based on the SimdFeatures struct detected at runtime.

ARM64 NEON Support

On Apple Silicon and ARM64 Linux systems, VelesDB utilizes crates/velesdb-core/src/simd_neon.rs. This file contains hand-written NEON intrinsics for dot products, Euclidean distance, and cosine similarity. The module is guarded by #[cfg(target_arch = "aarch64")], ensuring it compiles only on ARM64 targets where NEON is guaranteed.

WebAssembly SIMD128

For browser-based deployments, the crates/velesdb-wasm/src/simd.rs module provides SIMD-128 support through the wide crate. This abstraction automatically emits SIMD128 instructions when the WebAssembly runtime supports them, falling back to scalar operations otherwise. The wide::f32x8 vectors handle the vectorization transparently.

Scalar Fallback

If no SIMD features are detected, VelesDB defaults to pure Rust scalar loops defined within the same dispatch modules. These fallback implementations ensure functionality across all platforms while sacrificing performance.

Key Source Files and Dispatch Mechanism

The public API for SIMD operations resides in crates/velesdb-core/src/simd_dispatch.rs. This file defines the SimdFeatures struct (lines 70-84) and provides the primary entry points that forward to architecture-specific implementations.

Key functions exported from simd_dispatch.rs include:

• dot_product_dispatched(a: &[f32], b: &[f32]) -> f32
• euclidean_dispatched(a: &[f32], b: &[f32]) -> f32
• cosine_dispatched(a: &[f32], b: &[f32]) -> f32
• cosine_normalized_dispatched(a: &[f32], b: &[f32]) -> f32
• hamming_dispatched(a: &[f32], b: &[f32]) -> u32

These functions call into simd_native (for x86 and WASM) or simd_neon (for ARM64), which in turn use the is_x86_feature_detected! macro to select between AVX-512, AVX2, or scalar paths at runtime.

Available SIMD-Optimized Operations

VelesDB provides SIMD acceleration for the following vector-space operations:

• Dot Product: Sum of element-wise multiplication
• Euclidean Distance: L2 norm between vectors
• Cosine Similarity: Angle between vectors (includes normalized variant)
• Hamming Distance: Bitwise difference metric
• Jaccard Similarity: Set intersection over union

Each operation follows the same dispatch pattern, ensuring consistent performance characteristics across different hardware platforms.

Platform-Specific Usage Examples

Native Rust Binary (x86_64)

For standard Rust applications targeting x86_64, import the dispatch functions directly:

use velesdb_core::simd_dispatch::{
    dot_product_dispatched, euclidean_dispatched, 
    cosine_dispatched, hamming_dispatched
};

fn main() {
    let a = vec![0.1_f32; 768];
    let b = vec![0.2_f32; 768];

    let dot = dot_product_dispatched(&a, &b);
    let l2 = euclidean_dispatched(&a, &b);
    let cos = cosine_dispatched(&a, &b);
    let ham = hamming_dispatched(&a, &b);

    println!("dot={dot:.4}, euclidean={l2:.4}, cosine={cos:.4}, hamming={ham}");
}

The binary automatically utilizes AVX-512 or AVX2 if available, falling back to scalar math otherwise.

ARM64 with NEON

On Apple Silicon or ARM64 Linux, access the NEON-specific wrappers when you need guaranteed SIMD performance:

#[cfg(target_arch = "aarch64")]
use velesdb_core::simd_neon::{
    dot_product_neon_safe, euclidean_neon_safe, 
    cosine_neon_safe
};

#[cfg(target_arch = "aarch64")]
fn main() {
    let a = vec![1.0_f32, 2.0, 3.0, 4.0];
    let b = vec![4.0_f32, 3.0, 2.0, 1.0];

    unsafe {
        let dot = dot_product_neon_safe(&a, &b);
        let l2 = euclidean_neon_safe(&a, &b);
        let cos = cosine_neon_safe(&a, &b);
        
        println!("NEON → dot={dot}, euclidean={l2}, cosine={cos}");
    }
}

These functions are marked unsafe due to intrinsic usage, but the target_arch = "aarch64" guard ensures they only compile on compatible platforms.

WebAssembly Integration

For browser deployments, use the WASM-specific SIMD module:

// In crates/velesdb-wasm/src/lib.rs or similar
use velesdb_wasm::simd::{
    dot_product, euclidean_distance, cosine_similarity
};
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn compute_metrics(a: &[f32], b: &[f32]) -> JsValue {
    let dot = dot_product(a, b);
    let l2 = euclidean_distance(a, b);
    let cos = cosine_similarity(a, b);
    
    // Return as JavaScript object
    js_sys::Object::from_entries(&js_sys::Array::of3(
        &js_sys::Array::of2(&"dot".into(), &dot.into()),
        &js_sys::Array::of2(&"euclidean".into(), &l2.into()),
        &js_sys::Array::of2(&"cosine".into(), &cos.into()),
    )).unwrap().into()
}

The wide crate handles SIMD128 detection automatically when the target supports it.

Build Configuration and Target Flags

Configure your build environment based on the target platform to ensure optimal SIMD utilization:

Platform	Configuration	Build Command
x86_64 (AVX2/AVX-512)	Automatic detection; optionally use RUSTFLAGS="-C target-cpu=native" for maximum optimization	cargo build --release
ARM64 (NEON)	Target aarch64-unknown-linux-gnu or Apple Silicon targets	rustup target add aarch64-unknown-linux-gnu && cargo build --target aarch64-unknown-linux-gnu --release
WebAssembly (SIMD128)	Target wasm32-unknown-unknown with the wide crate feature enabled	rustup target add wasm32-unknown-unknown && cargo build -p velesdb-wasm --target wasm32-unknown-unknown --release
Generic (Scalar)	No special flags required; works on all platforms	cargo build --release

Summary

• Automatic dispatch – VelesDB selects the optimal SIMD implementation (AVX-512, AVX2, NEON, or WASM SIMD128) at runtime using CPU feature detection.
• Unified API – The simd_dispatch.rs module provides platform-agnostic functions like dot_product_dispatched and euclidean_dispatched that work across x86_64, ARM64, and WASM.
• Architecture-specific paths – Native x86 uses simd_native with is_x86_feature_detected!, ARM64 uses simd_neon.rs, and WASM uses velesdb-wasm/src/simd.rs with the wide crate.
• Zero configuration – SIMD optimizations activate automatically when building for the target platform; no manual feature flags are required beyond standard Rust target specifications.

Frequently Asked Questions

How does VelesDB detect which SIMD instructions are available?

VelesDB uses the is_x86_feature_detected! macro at runtime to check for avx512f, avx2, and popcnt CPU flags on x86_64 systems. This detection occurs inside simd_dispatch.rs (lines 70-84) where it populates the SimdFeatures struct. On ARM64, NEON is assumed available since the simd_neon.rs module is only compiled when target_arch = "aarch64". For WebAssembly, the wide crate automatically detects SIMD128 support in the runtime environment.

Can I force VelesDB to use a specific SIMD implementation instead of automatic dispatch?

No, VelesDB does not expose manual override flags for SIMD selection in the public API. The dispatch mechanism in simd_native/dispatch/mod.rs automatically selects the fastest available implementation based on the detected CPU features. However, you can influence the build by setting RUSTFLAGS="-C target-cpu=native" when compiling for x86_64, which allows the compiler to generate code assuming all local CPU features are available. For ARM64, you can directly use the simd_neon module functions if you need guaranteed NEON performance.

What vector operations are accelerated by SIMD in VelesDB?

VelesDB provides SIMD acceleration for dot_product_dispatched, euclidean_dispatched, cosine_dispatched, cosine_normalized_dispatched, and hamming_dispatched. These functions cover the essential vector similarity metrics used in semantic search and embedding comparisons. The underlying implementations in simd_native/dispatch/dot.rs, euclidean.rs, and cosine.rs contain scalar, 4-wide, 8-wide, and AVX-512 variants, while simd_neon.rs provides ARM64-optimized versions of the same operations.

Is WebAssembly SIMD support automatic when using VelesDB in the browser?

Yes, when using the velesdb-wasm crate, SIMD128 support is automatic through the wide crate abstraction. The crates/velesdb-wasm/src/simd.rs module uses wide::f32x8 vectors, which compile to SIMD128 instructions when the target supports them. You only need to build with the wasm32-unknown-unknown target; the wide crate handles runtime detection of SIMD capabilities in the WebAssembly runtime. If the browser does not support SIMD128, the code falls back to scalar loops without requiring changes to your application code.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}