[minmax] Add grid scaling to recompress API by arkrishn94 · Pull Request #1109 · microsoft/DiskANN

arkrishn94 · 2026-05-27T20:24:39Z

The original implementation of the recompression API for minmax didn't contain support to scale the grid during recompression. This was fine since it was being used by consumers at 4-bitrate only; now there is demand to test this with 2-bits for which scaling down the grid is necessary to improve recall.

Ran benchmarks to make sure results from benchmarking is identical to compressing from f32 directly.

Recall@10 on enron-email-1M-fbv4 (1,087,932 × 384, fp16 cosine, 1000 queries)

4-bit

Pipeline	g=1.00	g=0.90	g=0.60
f32 → 4 (direct)	0.9001	0.9084	0.8093
8 → 4 (recompress)	0.9001	0.9061	0.8088

2-bit

Pipeline	g=1.00	g=0.90	g=0.60
f32 → 2 (direct)	0.5970	0.6370	0.6952
8 → 2 (recompress)	0.5970	0.6375	0.6950

Recompressor is now a struct carrying a Positive<f32> grid_scale. Default preserves legacy behavior (g=1.0). The recompress kernel re-centers the source reconstruction range by grid_scale before quantizing to the lower bitwidth, allowing tighter packing of the distribution when recompressing from a higher to a lower bitwidth. Includes bit-for-bit oracle tests sweeping multiple grid scales for all supported (N,M) pairs.

Copilot

Pull request overview

Adds grid scaling support to the MinMax recompression path so lower-bit recompression can narrow or widen the target reconstruction range instead of always preserving the source range.

Changes:

Adds grid_scale: Positive<f32> to Recompressor with constructor/accessor APIs.
Updates recompression math to apply offset/scaling and clamp target codes.
Expands tests to sweep multiple grid-scale values and validate emitted metadata.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

codecov-commenter · 2026-05-27T20:44:57Z

Codecov Report

❌ Patch coverage is 93.87755% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 89.46%. Comparing base (e2dc9a0) to head (8c45a74).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
diskann-quantization/src/minmax/recompress.rs	93.87%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1109      +/-   ##
==========================================
- Coverage   89.46%   89.46%   -0.01%     
==========================================
  Files         482      482              
  Lines       91082    91099      +17     
==========================================
+ Hits        81491    81506      +15     
- Misses       9591     9593       +2

Flag	Coverage Δ
miri	`89.46% <93.87%> (-0.01%)`	⬇️
unittests	`89.11% <93.87%> (-0.01%)`	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
diskann-quantization/src/minmax/recompress.rs	`97.32% <93.87%> (+0.26%)`	⬆️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

These examples were intended for local benchmarking only and were unintentionally committed. Removing them; they remain in the working tree as untracked files.

@harsha-simhadri

# DiskANN v0.53.0 Release Notes ## Breaking Changes An AI generated, human reviewed list of changes is summarized below. ### Paged search overhauled — channel-based API ([#1078](#1078)) `PagedSearchState` and its `'static`-bound pause/resume model have been replaced with an async, channel-based interface. The recommended way to drive paged search is now via a `tokio::sync::mpsc` channel, with the searcher embedded in an otherwise-`'static` future. See the [rendered RFC](https://github.com/microsoft/DiskANN/blob/main/rfcs/01078-paged-search.md) for the new shape. Callers wired against `PagedSearchState` must migrate to the channel API. Users of paged search via `wrapped_async::DiskANNIndex` that know their inner futures will never suspend can use the new `wrapped_async::DiskANNIndex::paged_search_no_await`; this will efficiently run paged searches with minimal synchronization overhead. ### `DiskANNIndex::flat_search` removed ([#1076](#1076)) `DiskANNIndex::flat_search` and the `IdIterator` trait have been removed from the `diskann` crate. Equivalent functionality lives on the new inherent method `DiskIndexSearcher::flat_search` in `diskann-disk`. This unblocks the experimental directions in #1067 and #983. ```rust // Before diskann_index.flat_search(query, ...)?; // After disk_index_searcher.flat_search(query, ...).await?; ``` ### `DiskIndexSearcher::flat_search` now batched ([#1097](#1097)) The new `DiskIndexSearcher::flat_search` uses the bulk `pq_distances` path instead of one-vector-at-a-time `Accessor::build_query_computer` + `evaluate_similarity`. Downstream behavior is equivalent but tighter resource bounds apply. ### `centroid` removed from PQ interfaces ([#1010](#1010)) The dataset-centroid argument has been removed from `FixedChunkPQTable` construction, `populate`, and most other PQ APIs. The shift only ever worked for L2 distance and was silently ignored for inner-product / cosine, so passing it was a footgun. When an L2 shift is required, fold it into the PQ pivots instead (the library now does this internally). ```rust // Before let table = FixedChunkPQTable::new(.., centroid, ..); // After — drop the centroid argument let table = FixedChunkPQTable::new(.., ..); ``` ### Flat search interface ([#983](#983)) A new `flat` module in `diskann` adds a provider-agnostic brute-force search surface, mirroring the shape of graph search. Backends implement a single trait, `DistancesUnordered<C>` (in `flat/strategy.rs`), which fuses iteration and distance computation, allowing any backend (in-memory, quantized, disk, remote) to plug into a shared algorithm. See the [rendered RFC](https://github.com/microsoft/DiskANN/blob/main/rfcs/00983-flat-search.md). This is additive but is the new canonical surface — direct ad-hoc flat-search call sites should migrate. ### `bf_tree` extracted into `diskann-bftree` crate ([#1020](#1020)) The bf_tree provider has been moved out of `diskann-providers` (previously at `diskann-providers/src/model/graph/provider/async_/bf_tree/`) into a new standalone `diskann-bftree` crate. Along with the move: - Switched from PQ to spherical quantization. - Dropped dependencies on `DeletionCheck`, `AsDeletionCheck`, and `RemoveDeletedIdsAndCopy`. - Simplified generics. Consumers must update their `Cargo.toml` to depend on `diskann-bftree` and update import paths. ### `direct_distance_impl` and `inner_product_raw` re-exposed ([#1081](#1081)) `direct_distance_impl` (free function) and `FixedChunkPQTable::inner_product_raw` are `pub` again after being privatized in #1044. Restored to unblock a downstream user. Not breaking in the typical direction — this restores previously available API surface. ### MinMax `recompress` takes a grid-scale parameter ([#1109](#1109)) The MinMax `recompress` API now accepts a grid-scale parameter. ## New Features - SIMD-optimized L2-squared norm ([#1107](#1107)) - Significantly faster bitmap computation ([#1099](#1099)) - Large speedup on the bitmap construction path used by filtered search. - LLVM IR bloat regression check in CI ([#1083](#1083)) - CI now flags regressions in generated LLVM IR size, helping catch unintended monomorphization blow-ups. - Recall computation fix for under-k groundtruth ([#1069](#1069)) ## Merged PRs * Revise README for DiskANN3 by @harsha-simhadri in #1046 * [CI] Try to fix publishing step by @hildebrandmw in #1057 * [benchmark] Remove `DispatchRule` by @hildebrandmw in #1064 * [benchmark] Automatic Input Registration by @hildebrandmw in #1066 * Remove centroid from most PQ interfaces by @hildebrandmw in #1010 * [diskann/disk] Remove `flat_search` from `DiskANNIndex` by @hildebrandmw in #1076 * macos build and miri check to nightly by @harsha-simhadri in #1058 * [API] Make some methods public again by @hildebrandmw in #1081 * [benchmark] Simply `Inputs` more by @hildebrandmw in #1077 * Turn on stack protection for the diskann-garnet NuGet build by @jackmoffitt in #1082 * Fix options for diskann-garnet nuget pipeline by @jackmoffitt in #1091 * [CI] add LLVM IR bloat regression check by @arazumov in #1083 * Bump openssl from 0.10.79 to 0.10.80 by @dependabot[bot] in #1093 * [Disk CI benchmarks] Use 1ES.Pool=diskann-github by @arazumov in #869 * Fix recall computation for fewer than k groundtruth results by @magdalendobson in #1069 * bf_tree migration away from diskann-providers by @JordanMaples in #1020 * [RFC/diskann] Overhaul paged search by @hildebrandmw in #1078 * Remove unsafe code from compute_vec_l2sq by @arazumov in #1094 * Remove direct accessor call in `diskann-garnet` by @hildebrandmw in #1098 * Refactor `DiskIndexSearcher::flat_search` to use batching by @hildebrandmw in #1097 * [flat index] Flat Search Interface by @arkrishn94 in #983 * migrating multi-hop tests from diskann-providers to diskann by @JordanMaples in #928 * Significantly speed up bitmap computation by @magdalendobson in #1099 * `compute_vecs_l2sq`: Replace scalar L2 Squared norm with SIMD-optimized FastL2NormSquared by @arazumov in #1107 * [minmax] Add grid scaling to recompress API by @arkrishn94 in #1109 **Full Changelog**: v0.52.0...v0.53.0

arkrishn94 requested review from a team and Copilot May 27, 2026 20:24

Copilot started reviewing on behalf of arkrishn94 May 27, 2026 20:24 View session

Copilot AI reviewed May 27, 2026

View reviewed changes

Comment thread diskann-quantization/src/minmax/recompress.rs

Comment thread diskann-quantization/src/minmax/recompress.rs Outdated

arrayka reviewed May 27, 2026

View reviewed changes

Comment thread diskann-quantization/src/minmax/recompress.rs Outdated

Comment thread diskann-quantization/src/minmax/recompress.rs

Comment thread diskann-quantization/src/minmax/recompress.rs

arkrishn94 added 2 commits May 27, 2026 17:21

remove unsafe and test grid_scale

05e60f4

diskann-quantization: remove benchmark examples from branch

1431edf

These examples were intended for local benchmarking only and were unintentionally committed. Removing them; they remain in the working tree as untracked files.

arrayka approved these changes May 27, 2026

View reviewed changes

Comment thread fbv4_results.md Outdated

Comment thread diskann-quantization/src/minmax/recompress.rs

Delete fbv4_results.md

8c45a74

doliawu approved these changes May 27, 2026

View reviewed changes

arkrishn94 enabled auto-merge (squash) May 28, 2026 00:42

arkrishn94 merged commit e6c976f into main May 28, 2026
24 checks passed

arkrishn94 deleted the u/adkrishnan/recompress-grid-scale branch May 28, 2026 00:46

arkrishn94 mentioned this pull request May 28, 2026

Bump version to 0.53.0 #1111

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[minmax] Add grid scaling to recompress API#1109

[minmax] Add grid scaling to recompress API#1109
arkrishn94 merged 4 commits into
mainfrom
u/adkrishnan/recompress-grid-scale

arkrishn94 commented May 27, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

codecov-commenter commented May 27, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

Conversation

arkrishn94 commented May 27, 2026

Recall@10 on enron-email-1M-fbv4 (1,087,932 × 384, fp16 cosine, 1000 queries)

4-bit

2-bit

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

codecov-commenter commented May 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

codecov-commenter commented May 27, 2026 •

edited

Loading