Skip to main content

lattice_simd/
lib.rs

1//! SIMD vector operations for embedding similarity and compressed-vector search.
2//!
3//! Dispatch uses the best supported target kernel with scalar fallbacks; WASM
4//! SIMD128 is selected at compile time. The public SIMD surface is unstable.
5//!
6//! See docs/simd.md for the kernel family, dispatch, and quantization design.
7
8#![warn(missing_docs)]
9#![allow(clippy::clone_on_copy)]
10
11mod binary;
12mod cosine;
13mod distance;
14mod dot_product;
15mod error;
16mod int4;
17mod manhattan;
18mod normalize;
19mod quantized;
20mod tier;
21
22#[cfg(test)]
23mod tests;
24
25pub use binary::BinaryVector;
26pub use cosine::{
27    batch_cosine_one_vs_many, batch_cosine_similarity, cosine_similarity, cosine_similarity_fused,
28    cosine_similarity_pre_normalized, query_norm,
29};
30pub use distance::{euclidean_distance, squared_euclidean_distance};
31pub use dot_product::{
32    DotBatch4Kernel, DotKernel, batch_dot_product, dot_product, dot_product_batch4,
33    resolved_dot_product_batch4_kernel, resolved_dot_product_kernel,
34};
35pub use error::{Result, SimdError};
36pub use int4::{Int4Params, Int4Vector};
37pub use manhattan::manhattan_distance;
38pub use normalize::normalize;
39pub use quantized::{
40    I8DotKernel, QuantizationParams, QuantizedVector, cosine_similarity_i8, dot_product_i8,
41    dot_product_i8_raw, resolved_i8_dot_kernel,
42};
43pub use tier::{
44    NormalizationHint, PreparedQuery, PreparedQueryWithMeta, QuantizationTier, QuantizedData,
45    approximate_cosine_distance, approximate_cosine_distance_prepared,
46    approximate_cosine_distance_prepared_with_meta, approximate_dot_product,
47    approximate_dot_product_prepared, approximate_int4_batch_prepared,
48    approximate_int4_batch_prepared_into, approximate_int8_batch_prepared,
49    approximate_int8_batch_prepared_into, batch_approximate_cosine_distance_prepared,
50    batch_approximate_cosine_distance_prepared_into, is_unit_norm, prepare_query,
51    prepare_query_with_norm, try_approximate_cosine_distance_prepared,
52    try_approximate_dot_product_prepared,
53};
54
55use std::sync::OnceLock;
56
57/// **Unstable**: SIMD dispatch internals; fields may be added as new ISAs are supported.
58///
59/// SIMD configuration with runtime feature detection.
60#[derive(Debug, Clone, Copy, PartialEq, Eq)]
61pub struct SimdConfig {
62    /// **Unstable**: AVX-512F support available (x86_64).
63    pub avx512f_enabled: bool,
64    /// **Unstable**: AVX2 support available (x86_64).
65    pub avx2_enabled: bool,
66    /// **Unstable**: FMA (Fused Multiply-Add) support available (x86_64).
67    pub fma_enabled: bool,
68    /// **Unstable**: AVX-512F + AVX-512VNNI support available (x86_64).
69    pub avx512vnni_enabled: bool,
70    /// **Unstable**: NEON support available (aarch64/ARM64).
71    pub neon_enabled: bool,
72    /// **Unstable**: whether aarch64 FEAT_DotProd is available for SDOT/UDOT dispatch.
73    ///
74    /// Always false off aarch64. See [`docs/simd.md`](../docs/simd.md#dispatch-model) for availability rules.
75    pub dotprod_enabled: bool,
76}
77
78impl Default for SimdConfig {
79    fn default() -> Self {
80        Self::detect()
81    }
82}
83
84impl SimdConfig {
85    /// **Unstable**: feature detection details may change as ISA support expands.
86    pub fn detect() -> Self {
87        #[cfg(target_arch = "x86_64")]
88        {
89            let avx512f_enabled = is_x86_feature_detected!("avx512f");
90
91            Self {
92                avx512f_enabled,
93                avx2_enabled: is_x86_feature_detected!("avx2"),
94                fma_enabled: is_x86_feature_detected!("fma"),
95                avx512vnni_enabled: avx512f_enabled
96                    && is_x86_feature_detected!("avx512bw")
97                    && is_x86_feature_detected!("avx512vnni"),
98                neon_enabled: false,
99                dotprod_enabled: false,
100            }
101        }
102        #[cfg(target_arch = "aarch64")]
103        {
104            // NEON is mandatory on aarch64, always available.
105            // FEAT_DotProd (dotprod) is optional: required on Armv8.4+,
106            // optional on Armv8.2/v8.3. Detect at runtime.
107            Self {
108                avx512f_enabled: false,
109                avx2_enabled: false,
110                fma_enabled: false,
111                avx512vnni_enabled: false,
112                neon_enabled: true,
113                dotprod_enabled: std::arch::is_aarch64_feature_detected!("dotprod"),
114            }
115        }
116        #[cfg(target_arch = "wasm32")]
117        {
118            // No runtime detection on wasm32: `simd128` is either compiled in
119            // for the whole module (via `-C target-feature=+simd128`) or not.
120            // `cfg!` reads the same compile-time flag the `#[cfg(...)]` gates
121            // on the SIMD kernel functions themselves key off, so this stays
122            // consistent with which kernels actually exist in the binary.
123            Self {
124                avx512f_enabled: false,
125                avx2_enabled: false,
126                fma_enabled: false,
127                avx512vnni_enabled: false,
128                neon_enabled: false,
129                dotprod_enabled: false,
130            }
131        }
132        #[cfg(not(any(
133            target_arch = "x86_64",
134            target_arch = "aarch64",
135            target_arch = "wasm32"
136        )))]
137        {
138            Self {
139                avx512f_enabled: false,
140                avx2_enabled: false,
141                fma_enabled: false,
142                avx512vnni_enabled: false,
143                neon_enabled: false,
144                dotprod_enabled: false,
145            }
146        }
147    }
148
149    /// **Unstable**: reports whether this wasm32 artifact was built with SIMD128.
150    ///
151    /// See [`docs/simd.md`](../docs/simd.md#dispatch-model) for the compile-time dispatch model.
152    #[inline]
153    pub fn simd128_enabled(&self) -> bool {
154        cfg!(all(target_arch = "wasm32", target_feature = "simd128"))
155    }
156
157    /// **Unstable**: check if any SIMD is available; logic may expand with new ISAs.
158    #[inline]
159    pub fn simd_available(&self) -> bool {
160        self.avx512f_enabled
161            || self.avx512vnni_enabled
162            || self.avx2_enabled
163            || self.neon_enabled
164            || self.simd128_enabled()
165    }
166
167    /// Force scalar-only mode (useful for testing).
168    #[cfg(test)]
169    pub fn scalar_only() -> Self {
170        Self {
171            avx512f_enabled: false,
172            avx2_enabled: false,
173            fma_enabled: false,
174            avx512vnni_enabled: false,
175            neon_enabled: false,
176            dotprod_enabled: false,
177        }
178    }
179}
180
181// Process-wide SIMD configuration (detected once).
182static SIMD_CONFIG: OnceLock<SimdConfig> = OnceLock::new();
183
184/// **Unstable**: SIMD dispatch internal; shape may change as new backends are added.
185///
186/// The config is detected once per process and cached.
187#[inline]
188pub fn simd_config() -> SimdConfig {
189    *SIMD_CONFIG.get_or_init(SimdConfig::detect)
190}