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

> Discover how VelesDB automatically leverages SIMD optimizations like AVX-512, AVX2, NEON, and WASM SIMD128. Experience enhanced performance without manual configuration thanks to runtime CPU feature detection.

- Repository: [Wiscale/velesdb](https://github.com/cyberlife-coder/velesdb)
- Tags: how-to-guide
- Published: 2026-02-28

---

**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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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:

```rust
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:

```rust
#[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:

```rust
// 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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/simd_neon.rs), and WASM uses [`velesdb-wasm/src/simd.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/simd_dispatch.rs) (lines 70-84) where it populates the `SimdFeatures` struct. On ARM64, NEON is assumed available since the [`simd_neon.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/simd_native/dispatch/dot.rs), [`euclidean.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/euclidean.rs), and [`cosine.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/cosine.rs) contain scalar, 4-wide, 8-wide, and AVX-512 variants, while [`simd_neon.rs`](https://github.com/cyberlife-coder/velesdb/blob/main/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`](https://github.com/cyberlife-coder/velesdb/blob/main/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.