# lattice-simd
SIMD vector math for Lattice: dot product, cosine similarity, Euclidean and
Manhattan distance, L2 normalization, and approximate operations over INT8,
INT4 and binary quantized vectors, including tiered storage with prepared
queries.
Kernels cover AVX-512, AVX2+FMA, NEON and WASM SIMD128, with a scalar fallback
for every operation. On x86_64 and aarch64 the kernel is chosen at runtime from
the detected CPU features (`SimdConfig`); on wasm32 it is chosen at compile time
from `target_feature = "simd128"`.
The crate has no internal dependencies. `lattice-embed` re-exports it as
`lattice_embed::simd`, so code written against either path uses the same items.
```rust
use lattice_simd::{cosine_similarity, dot_product, normalize};
let mut a = vec![1.0_f32, 2.0, 3.0];
let b = vec![3.0_f32, 2.0, 1.0];
let dot = dot_product(&a, &b);
let cos = cosine_similarity(&a, &b);
normalize(&mut a);
assert!(dot > 0.0 && cos > 0.0);
```
The SIMD surface is marked unstable. See [docs/simd.md](docs/simd.md) for the
kernel family, dispatch, numerical behaviour and the quantized-vector formats.
## Crate reference
The sections below are generated by `scripts/crate-readme.py` from the source tree and are refreshed after pushes to `main`. Text between the `generated` markers is overwritten; edit the source or the script instead.
### Facts
- Version: `0.15.0`
- Minimum supported Rust version: `1.93`
- Edition: `2024`
- License: `MIT OR Apache-2.0`
- crates.io: <https://crates.io/crates/lattice-simd>
- API documentation: <https://docs.rs/lattice-simd>
### Source layout
The tracked files under `src/`; each Rust file shows the first sentence of its `//!` module documentation.
<details>
<summary><code>src/</code>: 16 files</summary>
- `binary.rs`: Binary sign quantization and Hamming-distance operations.
- `binary/`
- `tests.rs`
- `cosine.rs`: SIMD cosine-similarity kernels and batch variants.
- `distance.rs`: SIMD Euclidean and squared-Euclidean distance kernels.
- `dot_product.rs`: SIMD float dot-product kernels, including a one-query/four-candidate path.
- `error.rs`: Errors returned by prepared quantized-tier operations.
- `int4.rs`: INT4 packed-vector quantization and approximate dot products.
- `int4/`
- `tests.rs`
- `lib.rs`: SIMD vector operations for embedding similarity and compressed-vector search.
- `manhattan.rs`: SIMD Manhattan (L1) distance kernels.
- `normalize.rs`: SIMD in-place L2 normalization kernels.
- `quantized.rs`: INT8 vector quantization and approximate similarity kernels.
- `quantized/`
- `simd_parity_tests.rs`
- `tests.rs`: Tests for SIMD operations.
- `tier.rs`: Quantization tiers, prepared queries, and unified distance dispatch.
- `tier/`
- `tests.rs`
</details>
Targets declared by the manifest, including the ones Cargo discovers by directory:
- lib (1): `lattice_simd`
### Statistics
Rust lines by kind (code, comment, blank; doc comments count as comment), test functions (`#[test]` and `#[<runtime>::test]` attributes), items declared `pub` (not `pub(crate)`; reachability through private modules is not resolved) and occurrences of the `unsafe` keyword outside comments and strings.
| `src/` | 16 | 6524 | 1049 | 1105 | 131 | 105 | 106 |
| total | 16 | 6524 | 1049 | 1105 | 131 | 105 | 106 |
Other tracked files (the README excluded):
| `.md` | 1 | 26.4 KiB |
| `.toml` | 1 | 600 B |
### In-crate documentation
- [SIMD kernels and quantized-vector paths](docs/simd.md) (`docs/simd.md`)
### Features
The manifest declares no features.
### Workspace dependencies
- Depends on: no other crate in this workspace
- Used by: `lattice-embed`
### Architecture decisions
No ADR under `docs/adr/` names `lattice-simd` or `crates/simd/`.
### Benchmarks
No CI benchmark data for this crate: `bench-update.yml` records only `lattice-embed` `simd`, `lattice-inference` `elementwise_cpu_bench`.