Skip to content

Commit 1dee24a

Browse files
committed
address more comments
Signed-off-by: Connor Tsui <[email protected]>
1 parent 681fb8e commit 1dee24a

1 file changed

Lines changed: 21 additions & 16 deletions

File tree

‎benchmarks/vector-search-bench/src/distortion.rs‎

Lines changed: 21 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,10 @@
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.
206205
fn 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.
255256
fn 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`].
265267
fn 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

Comments
 (0)