Method encode

nodedb-codec/src/vector_quant/bbq.rs:187–244

(&self, v: &[f32])

    type Query = BbqQuery;

    fn encode(&self, v: &[f32]) -> BbqQuantized {
        // Step 1: center.
        let mut centered = Vec::with_capacity(self.dim);
        self.center(v, &mut centered);

        // Step 2: pack sign bits.
        let packed = Self::pack_signs(&centered);

        // Step 3: corrective factors.
        //
        // residual_norm (4 B → header.residual_norm):
        //   ‖v′‖  where v′ = v − c.  Used in the symmetric distance estimate.
        let residual_norm = Self::norm(&centered);

        // dot_quantized (4 B → header.dot_quantized):
        //   ⟨v′, sign(v′)⟩ / ‖v′‖.  Measures how well the sign quantization
        //   captures the direction of v′.
        let sign_fp: Vec<f32> = centered
            .iter()
            .map(|&x| if x >= 0.0 { 1.0 } else { -1.0 })
            .collect();
        let dot_vs = Self::dot(&centered, &sign_fp);
        let dot_quantized = if residual_norm > 0.0 {
            dot_vs / residual_norm
        } else {
            0.0
        };

        // global_scale (4 B → header.global_scale):
        //   ⟨v′, c⟩ / ‖c‖.  Captures how aligned the centered vector is with
        //   the centroid direction — used as a query-alignment corrective.
        let centroid_norm = Self::norm(&self.centroid);
        let dot_vc = Self::dot(&centered, &self.centroid);
        let query_alignment = if centroid_norm > 0.0 {
            dot_vc / centroid_norm
        } else {
            0.0
        };

        // reserved[0..2]: 2 bytes reserved for future correctives (zero-filled).
        let reserved = [0u8; 8];
        // reserved[0..2] are the 2 reserved corrective bytes; remainder is zero.

        let header = QuantHeader {
            quant_mode: QuantMode::Bbq as u16,
            dim: self.dim as u16,
            global_scale: query_alignment,
            residual_norm,
            dot_quantized,
            outlier_bitmask: 0,
            reserved,
        };

        let uqv = UnifiedQuantizedVector::new(header, &packed, &[]).expect(
            "BBQ encode: UnifiedQuantizedVector construction must succeed with no outliers",
        );
        BbqQuantized(uqv)
    }