Module sparse 

Distance kernels for sparse float32/float16 vectors.

Storage model

Each operand is a pair of parallel slices:

• idx: nnz dimension indices of a generic integer type (u16, u32, …), sorted ascending and unique;
• val: nnz values parallel to idx (f32, or f16 via Half).

Indices absent from an operand are implicit zeros.

Warning

The kernels do not verify that idx is sorted and unique. Violating this yields incorrect results, not undefined behavior. Callers that cannot otherwise guarantee this invariant can check it with indices_sorted_unique.

Kernels

• Inner product / cosine numerator — intersection merge over the two sorted index arrays; only matching indices contribute.
• Cosine denominator — each operand’s own L2 norm, computed by reusing crate::norm::FastL2Norm (a sparse vector’s norm is just the L2 norm of its value array).
• L2 — direct union merge of squared differences, sqrt(Σ (x_i − y_i)²).

Accumulation is in f32. The merge is scalar. A disjoint-range fast-out skips the intersection merge when the two index ranges cannot overlap.

These functions return the mathematical value of each metric. Any similarity-score transform (inner product x -> -x, cosine x -> 1 - x) is applied by the caller.

Structs

LengthMismatch

Error returned when a sparse operand’s index and value slices differ in length.

Functions

cosine_f16

Cosine similarity for f16 operands, clamped to [-1, 1]; 0 when either norm underflows or the operands are disjoint. Values are pre-widened once and reused for the numerator and both norms.

cosine_f32

Cosine similarity dot / (‖x‖·‖y‖) for f32 operands, clamped to [-1, 1]; 0 when either norm underflows or the operands are disjoint. Norms reuse crate::norm::FastL2Norm.

indices_sorted_unique

Returns true if idx is sorted ascending with no duplicates.

inner_product_f16

Σ x·y over matching indices for f16 operands; a disjoint-range fast-out skips widening when the operands cannot intersect.

inner_product_f32

Σ x·y over matching indices for f32 operands.

l2_f16

sqrt(Σ (x_i − y_i)²) for f16 operands; values are pre-widened to f32, then reuse the f32 union merge.

l2_f32

sqrt(Σ (x_i − y_i)²) for f32 operands.