Module vector_math 

Element-wise vector math nodes (type_system_alignment.md §8.2).

These are the first compute-shaped (rather than I/O-shaped) consumers of the typed-vector family: perturbing query vectors, computing ground-truth distances in evaluations, normalizing embeddings. On jit builds the f32 hot loops execute through the cranelift-SIMD kernels (compile::jit::simd — F32X4 chunked with scalar tails); without jit, or if host ISA construction fails, the scalar reference loops below run instead. SIMD accumulation reassociates float addition, so dot products may differ from the scalar reference in the final ulps — both orders are equally valid IEEE 754 sums.

Length mismatches panic with both lengths named: silently truncating to the shorter operand would corrupt distance semantics (“never ignore silently”).

Structs

HashVec

hash_vec(seed, dim) — deterministic synthetic f32 vector: element i is the SplitMix64 hash of (seed, i) mapped into [-1, 1). The canonical generator for synthetic embeddings — equal seeds always produce the identical vector, so dataset- free vector workloads stay replayable. Pairs with vec_norm for unit vectors.

LidMle

lid_mle(distances, k) — Levina–Bickel maximum-likelihood estimate of the local intrinsic dimensionality at one query point, from its sorted ground-truth nearest-neighbor distances.

VecAdd

vec_add(a, b) — element-wise sum of two f32 vectors. Panics when the lengths differ.

VecCosine

vec_cosine(a, b) — cosine similarity of two f32 vectors: dot(a,b) / (|a| * |b|). Returns 0.0 when either vector has zero magnitude (the conventional degenerate-case value: no direction, no similarity). Panics when the lengths differ.

VecDot

vec_dot(a, b) — dot product of two f32 vectors, widened to f64 on the output wire. Panics when the lengths differ.

VecL2

vec_l2(a, b) — Euclidean (L2) distance between two f32 vectors. Panics when the lengths differ.

VecNorm

vec_norm(a) — scale an f32 vector to unit L2 magnitude. A zero vector passes through unchanged (there is no direction to normalize onto, and emitting NaNs would poison downstream distance math silently).

VecScale

vec_scale(a, k) — multiply every element of an f32 vector by scalar k (applied at f32 precision).

Xxhash3Vec

xxhash3_vec(seed, dim) — deterministic synthetic f32 vector using xxHash3.

Functions

add_f32

a + b element-wise, as a new vector.

add_f32_into

a + b element-wise into out, which is cleared first.

check_lens

Panics with both lengths named when two operands differ in length.

cosine_f32

The cosine similarity of vec_cosine.

dot_f32

The dot product, through the SIMD kernel where the host has one.

dot_scalar

The scalar dot product: the reference the SIMD kernel is checked against.

hash_vec_into

The vector of hash_vec into out, which is cleared first.

l2sq_f32

The squared L2 distance, through the SIMD kernel where the host has one.

l2sq_scalar

The scalar squared L2 distance: the reference the SIMD kernel is checked against.

lid_mle_of

The estimate of lid_mle.

norm_f32_into

a scaled to unit L2 magnitude into out; a itself when its magnitude is zero.

scale_f32

a * k element-wise, as a new vector.

scale_f32_into

a * k element-wise into out, which is cleared first.

xxhash3_vec_into

The vector of xxhash3_vec into out, which is cleared first.