Module halfvec 

v6.0.3 — halfvec: IEEE-754 binary16 (F16) per-element storage.

Stable Rust 1.96 (this workspace) does not yet expose a stable f16 primitive or stable core::arch::aarch64 f16 intrinsics (rust-lang/rust#116909, #125606). v6.0.3 ships with a hand- rolled IEEE-754 binary16 codec on top of Vec<u8> carrying raw little-endian u16 bits. NEON f16 SIMD lands as v6.0.6 or whenever the stable toolchain catches up.

Layout per cell: [u16 LE × dim]. Dim = bytes.len() / 2.

Codec rounding: round-to-nearest-even on overflow / underflow (matches f32 as f16 semantics on hosts that do have the primitive). Special values:

• ±0.0 → bit-exact ±0.0 half.
• ±∞ → bit-exact ±∞ half.
• NaN → quiet NaN half (sign + payload preserved as far as the 10-bit mantissa allows; signalling/quiet bit is forced set so the value can’t decode back as inf).
• Subnormals + overflow → flushed to 0 and ±∞ respectively per IEEE 754-2008 §7.4.

Structs

HalfVector

SQ8 / SQ4 / SQ16 share an Sq*Vector-shaped struct; halfvec follows the same pattern. bytes always has even length; the invariant is enforced by every constructor in this module.

Functions

f16_from_f32_bits

Convert one f32 (passed as raw bits) to f16 (raw bits).

f16_to_f32_bits

Convert one f16 (raw bits) to f32 (raw bits). Exact for every finite f16; preserves sign + NaN-ness.

half_cosine_distance_asymmetric

Cosine distance 1 - dot / (||a|| * ||q||). Fused SIMD path; norm-sqrt + zero-guard live in the safe wrapper.

half_inner_product_asymmetric

Negated dot product (pgvector <#> convention). Fused SIMD path.

half_l2_distance_sq

Symmetric L2² between two f16 cells. Used during HNSW build.

half_l2_distance_sq_asymmetric

L2² distance between an f16 cell and an f32 query, fused so no Vec<f32> ever materialises. Dispatches to NEON for production- shaped dims (multiples of 8); scalar fallback otherwise.