Module quantization 

Vector quantization for IVF indexes

TurboQuant (tq) is the float codec: training-free, used by both the per-segment flat scan and the trained-router IVF-TQ leaves.

Structs

TqCodec

Complete TQ codec for one field dimension. Cheap to build (sub-millisecond) and immutable; share via Arc per open segment.

TqEncodeScratch

Reusable per-thread encode buffers (hot-path allocation hygiene).

TqFlatBuilder

Streaming builder for one segment’s TQ payload: doc/ordinal columns plus a block-packed codes column ready for ann_disk serialization.

TqQueryPlan

Per-query LUTs: padded_dim × 16 i8 tables (globally-scaled quantizations) for the block kernels. The intermediate f32 tables are dropped after quantization — they are not read on the search path.

Constants

TQ_BLOCK_LANES

Vectors per scoring block; one lane per vector.

TQ_CODEC_VERSION

Bumping this refuses to mix payloads across incompatible codec revisions. v2: padding-free 3-round rotation (sub-FWHT + signs + permutation per round) replaced the single-round power-of-two-padded FWHT — 768-dim codes shrank 33% and the codebook density now uses the true dimension.

Functions

tq_block_bytes

Bytes of one scoring block: 16 f32 gammas + 16 packed nibble rows.

tq_codes_column_len

Total codes-column bytes for count vectors (final block zero-padded).

tq_codes_column_len_checked

Overflow-checked tq_codes_column_len for untrusted header values.

tq_expected_fingerprint

Fingerprint every payload built for dim must carry (no codebook build).

tq_ivf_block_bytes

Bytes of one IVF-TQ scoring block: 16 f32 residual scales + 16 f32 gammas

tq_ivf_codes_column_len_checked

Overflow-checked IVF-TQ codes-column length for untrusted header values.

tq_pack_block

Pack up to 16 nibble rows (+ gammas) into one block. Missing lanes are zero-filled. rows are padded_dim-length 0..=15 values.

tq_pack_ivf_block

Pack an IVF-TQ block: per-lane residual scales, gammas, then nibbles.

tq_padded_dim

Code-layout dimension: the input dimension rounded up to an even count (two 4-bit coordinates per byte), floored at [TQ_MIN_PADDED_DIM]. Since codec v2 the rotation is padding-free, so this tracks the true dimension instead of the next power of two. Cheap; usable for header validation without building a codec.

tq_score_block

Score one block (16 lanes) into scores. block is [16 × f32 gamma][padded_dim × 8 packed nibbles]; lanes past the run’s vector count hold zero padding and must be ignored by the caller.

tq_score_ivf_block

Score one IVF-TQ block: score[lane] = cluster_dot + scale · (base + gamma · qjl), where cluster_dot = ⟨normalized query, centroid⟩ is the probed cluster’s shared contribution and scale = ‖residual‖.

tq_shared_codec

Process-wide codec cache. A codec is a pure function of the dimension and costs a Lloyd solve to build; segment opens and merges share one instance per dimension instead of re-deriving it.