33
44//! TurboQuant distortion measurement on real vector datasets.
55//!
6- //! Reports per-vector NMSE (`||x - x'||^2 / ||x||^2 = ||unit(x) - unit(x')||^2`) and per-
7- //! vector squared cosine-similarity error (`(cos(y_i, x_i) - cos(y_i, x'_i))^2`) against a
8- //! set of independently sampled unit-norm probe vectors `y_i`, after a full encode and
9- //! decode roundtrip through the [`vortex_tensor::encodings::turboquant`] scheme. This is
10- //! the same TurboQuant implementation the search subcommand stores on disk via
11- //! [`BtrBlocksCompressorBuilder::with_turboquant`](vortex_btrblocks::BtrBlocksCompressorBuilder).
6+ //! Reports the normalized mean square error (`||x - x'||^2 / ||x||^2`) and the squared
7+ //! cosine-similarity error (`(cos(y_i, x_i) - cos(y_i, x'_i))^2`) against a set of independently
8+ //! sampled unit-norm probe vectors `y_i`, after a full encode and decode roundtrip through the
9+ //! [`vortex_tensor::encodings::turboquant`] scheme.
1210//!
1311//! NMSE rather than raw SSE because TurboQuant internally normalizes each input to unit
1412//! norm before quantizing (storing `||x||` separately), so the paper's Stage-1 bound
@@ -93,9 +91,9 @@ pub struct DistortionReport {
9391 pub rounds : u8 ,
9492 /// Number of base vectors sampled.
9593 pub samples : usize ,
96- /// Per-vector NMSE , `||x - x'||^2 / ||x||^2`, equal to `||unit(x) - unit(x') ||^2`.
94+ /// Normalized squared reconstruction error per row , `||x - x'||^2 / ||x||^2`.
9795 pub reconstruction : DistortionStats ,
98- /// Per-vector squared cosine-similarity error against a random unit-norm probe `y_i`,
96+ /// Squared cosine-similarity error per row against a random unit-norm probe `y_i`,
9997 /// `(cos(y_i, x_i) - cos(y_i, x'_i))^2`.
10098 pub decoded_cosine : DistortionStats ,
10199}
@@ -201,30 +199,31 @@ fn pairs_per_row(flat: &[f32], num_rows: usize) -> Result<usize> {
201199 Ok ( flat. len ( ) / num_rows)
202200}
203201
204- /// Per-vector NMSE, `||x - x'||^2 / ||x||^2 = ||unit(x) - unit(x')||^2`. Zero-norm rows
205- /// report `0.0` (encoder maps zero in to zero out, so the unit-norm residual is `0`).
202+ /// Normalized squared reconstruction error per row, `||x - x'||^2 / ||x||^2`. Zero-norm
203+ /// rows are dropped from the sample because NMSE is undefined when `||x|| = 0`, and our
204+ /// vector datasets are not expected to contain zero vectors.
206205fn reconstruction_nmse (
207206 original : & [ f32 ] ,
208207 reconstructed : & [ f32 ] ,
209208 dim : usize ,
210209 num_rows : usize ,
211210) -> Vec < f32 > {
212211 ( 0 ..num_rows)
213- . map ( |row| {
212+ . filter_map ( |row| {
214213 let start = row * dim;
215214 let end = start + dim;
216215 let orig = & original[ start..end] ;
217216 let recon = & reconstructed[ start..end] ;
218217 let norm_sq: f32 = orig. iter ( ) . map ( |& v| v * v) . sum ( ) ;
219218 if norm_sq == 0.0 {
220- return 0.0 ;
219+ return None ;
221220 }
222221 let err_sq: f32 = orig
223222 . iter ( )
224223 . zip ( recon. iter ( ) )
225224 . map ( |( & a, & b) | ( a - b) * ( a - b) )
226225 . sum ( ) ;
227- err_sq / norm_sq
226+ Some ( err_sq / norm_sq)
228227 } )
229228 . collect ( )
230229}
@@ -252,6 +251,8 @@ fn random_unit_vectors(num_rows: usize, dim: usize, seed: u64) -> Result<Vec<f32
252251}
253252
254253/// Cosine similarity of two equal-length vectors, returning `0.0` if either has zero norm.
254+ /// A zero-norm decoded vector represents genuine quantizer failure, so the caller still
255+ /// gets a defined per-row error that reflects the lost direction.
255256fn cosine ( a : & [ f32 ] , b : & [ f32 ] ) -> f32 {
256257 let dot: f32 = a. iter ( ) . zip ( b. iter ( ) ) . map ( |( & x, & y) | x * y) . sum ( ) ;
257258 let norm_a: f32 = a. iter ( ) . map ( |& v| v * v) . sum :: < f32 > ( ) . sqrt ( ) ;
@@ -261,7 +262,8 @@ fn cosine(a: &[f32], b: &[f32]) -> f32 {
261262}
262263
263264/// Per-row squared cosine-similarity error against probe `y_i`,
264- /// `(cos(y_i, x_i) - cos(y_i, x'_i))^2`.
265+ /// `(cos(y_i, x_i) - cos(y_i, x'_i))^2`. Rows whose original `x_i` has zero norm are
266+ /// dropped, matching [`reconstruction_nmse`].
265267fn squared_cosine_errors (
266268 original : & [ f32 ] ,
267269 reconstructed : & [ f32 ] ,
@@ -270,14 +272,17 @@ fn squared_cosine_errors(
270272 num_rows : usize ,
271273) -> Vec < f32 > {
272274 ( 0 ..num_rows)
273- . map ( |row| {
275+ . filter_map ( |row| {
274276 let start = row * dim;
275277 let end = start + dim;
276278 let xi = & original[ start..end] ;
277279 let xi_dec = & reconstructed[ start..end] ;
278280 let yi = & probes[ start..end] ;
281+ if xi. iter ( ) . map ( |& v| v * v) . sum :: < f32 > ( ) == 0.0 {
282+ return None ;
283+ }
279284 let diff = cosine ( yi, xi) - cosine ( yi, xi_dec) ;
280- diff * diff
285+ Some ( diff * diff)
281286 } )
282287 . collect ( )
283288}
0 commit comments