[juchen-ms (partychen)]

• Does this PR have a descriptive title that could go in our release notes?
• Does this PR add any new dependencies?
• Does this PR modify any existing APIs?
• Is the change to the API backwards compatible?
• Should this result in any changes to our documentation, either updating existing docs or adding new ones?

No new dependencies. Public additions are backward-compatible SIMD trait implementations. The matrix kernel and BitSlice::decode_into remain pub(crate); existing distance APIs and canonical MinMax storage are unchanged. Contracts and safety requirements are documented inline.

Reference Issues/PRs

Reworks the matrix-kernel portion of #1394 into a standalone implementation. Uses SIMD reinterpretation and maddubs support from #1445 and #1479.

What does this implement/fix? Briefly explain your changes.

Adds an internal matrix MaxSim kernel for MinMax A/B inputs with 1-8 bits per code, supporting all 64 input-width combinations through the available numeric layouts. A is packed once and reused across B comparisons; each call writes one compensated maximum inner product per A row without materializing the full pairwise score matrix.

Preparation and execution

• Architecture-independent A packing uses From<u8> and stores coefficients per physical panel. Internal A/B views bind codes, coefficients, and dimensions together instead of passing unrelated slices through the kernel.
• The existing Drive -> PanelKernel -> MicroKernel structure prepares each B tile once and reuses it across A panels.
• B decoding is shared through BitSlice<'_, NBITS, Unsigned, Dense>::decode_into, not MinMax-local bit-width special cases. It applies conversion while writing, ignores unused trailing bits, and rejects a length mismatch before writing or invoking the callback.
• B scratch stores only the three compensation coefficients needed for computation and zero-pads code rows to PACK. Cache estimates use the prepared payload sizes. Physical stride is separate from logical K, so contraction can load complete packs while compensation uses the original dimension.
• ExtraWide<MR, PACK> exposes numeric backend operations without input-width parameters. Concrete load/store operations establish register extents. The Driver derives K and A's width from the packed input and retains the integer-range and B-width checks.
• Driver panel widths are NR=2, 4, or 8, expressed by concrete PanelKernel implementations. Each handles only its applicable remainders; unsupported NR configurations do not implement the required trait.

Available layouts

All layouts accept A_BITS=1-8. MR counts A rows per microkernel; PACK counts contraction elements processed together. These are available layouts, not an automatic selection policy.

Backend/path	MR	PACK	Prepared A / B	Supported B_BITS
Scalar byte	16	4	u8 / i8	1-7
Scalar general	8, 16	2	i16 / i16	1-8
V3 byte	8, 16	4	u8 / i8	1-6
V3 general	8, 16	2	i16 / i16	1-8
V4 byte	16	4	u8 / i8	1-7
V4 general	16	2	i16 / i16	1-8
Neon + dotprod	8, 16	4	u8 / u8	1-8

The byte limits prevent signed-byte misinterpretation and, on V3, saturation of intermediate i16 sums. They guarantee correctness for the full A code range, not just a particular A_BITS. Full-range eight-bit B uses the i16 path on Scalar/x86 and unsigned byte dots on Neon; widening does not requantize the inputs.

The original V3 byte layout remains alongside the general path. MR=16 V3 compensation finishes one native eight-row half before processing the other, and MR=8 alternatives are available. These changes are not a claim that generated code is spill-free or that one layout is optimal for every workload.

Behavior and tests

• Each drive overwrites C with unnegated maximum inner products. NaN candidates are ignored; empty B or all-NaN comparisons leave negative infinity.
• The internal Driver requires nonempty A, positive K, and matching dimensions/output length.
• K is bounded by i32::MAX / ((2^A_BITS - 1) * (2^B_BITS - 1)): 561,433 for 8x4/4x8 and 33,025 for 8x8. Conversion to f32 may still round.
• Tests separate format preparation from numeric execution: all input widths are covered in packing/decoding, all 64 width pairs have arithmetic-limit checks, and representative end-to-end cases cover tiling, tails, compensation, empty B, and smaller MR layouts.
• Direct microkernel cases cover NaNs and preservation of existing maxima. Numeric references are cross-checked against the existing pairwise implementations. The former per-width/per-backend full-Driver sweep and redundant ownership/reuse test were removed to reduce test execution and monomorphization cost; necessary layout/remainder specializations remain.

Any other comments?

Scope: Factory/ISA selection, public prepared-query distance integration, distance negation/no-match adaptation, externally owned/FFI layouts, relocation of the pairwise implementation into fallback, and benchmark integration remain follow-up work. No temporary performance or code-generation tooling is included.

Validation at 0977338a -- Windows x86-64:

Command	Result
cargo fmt --all --check	Passed
cargo test -p diskann-quantization --lib --quiet -- bits::slice::tests::test_decode_into matrix_kernels::maxsim::packed_minmax_x_unpacked_minmax	Passed: 28 test functions (3 decoder tests and 25 kernel tests)
cargo clippy --workspace --all-targets --quiet -- -D warnings	Passed before committing the same source tree
cargo clippy -p diskann-quantization -p diskann-wide --all-targets --target aarch64-pc-windows-msvc --quiet -- -D warnings	Passed; ARM cross-compilation/lint only

Scalar and V3 execute locally; V4 test bodies are conditionally skipped on this host but still compiled. Neon execution, SDE/Miri, and coverage were not rerun for this head. Earlier CI/coverage results and exploratory performance timings are not claimed as validation of this revision.

[Copilot]

🔵 Needs a closer look

The new unsafe SIMD paths require cross-platform validation and final human review.

0 open findings

What changed in this PR

Adds a standalone quantized MaxSim kernel to DiskANN’s matrix kernels, leaving distance API integration for a follow-up.

Changes:

• Implements packed-A, B-tiled computation for Scalar, V3, V4, and Neon.
• Adds compensated inner products and NaN-aware maximum reduction.
• Adds supporting SIMD conversions and regression coverage.

File	Description
diskann-wide/​src/​reference.rs	Adds reference u32-to-f32 conversion.
diskann-wide/​src/​emulated.rs	Adds and tests 16-lane i32-to-f32 conversion.
diskann-wide/​src/​arch/​x86_64/​v4/​conversion.rs	Adds and tests AVX-512 conversion.
diskann-wide/​src/​arch/​x86_64/​v3/​conversion.rs	Adds and tests split-vector conversion.
diskann-wide/​src/​arch/​aarch64/​u32x4_.rs	Adds and tests Neon conversion and reinterpretation.
diskann-quantization/​src/​matrix_kernels/​maxsim/​packed_minmax8_x_unpacked_minmax4.rs	Implements the kernel, backends, and regression tests.
diskann-quantization/​src/​matrix_kernels/​maxsim/​mod.rs	Registers the kernel pending integration.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

❌ Patch coverage is 94.83538% with 80 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.11%. Comparing base (2ff131f) to head (76189d3).

Files with missing lines	Patch %	Lines
..._kernels/maxsim/packed_minmax_x_unpacked_minmax.rs	94.63%	77 Missing ⚠️
diskann-quantization/src/bits/slice.rs	97.32%	3 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1494      +/-   ##
==========================================
+ Coverage   91.06%   91.11%   +0.05%     
==========================================
  Files         591      592       +1     
  Lines      122196   123745    +1549     
==========================================
+ Hits       111275   112754    +1479     
- Misses      10921    10991      +70     

Flag	Coverage Δ
miri	91.11% <94.83%> (+0.05%)	⬆️
unittests	90.82% <94.77%> (+0.05%)	⬆️

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

Files with missing lines	Coverage Δ
diskann-wide/src/arch/x86_64/v3/conversion.rs	100.00% <100.00%> (ø)
diskann-wide/src/arch/x86_64/v4/conversion.rs	0.00% <ø> (ø)
diskann-wide/src/emulated.rs	100.00% <ø> (ø)
diskann-quantization/src/bits/slice.rs	97.32% <97.32%> (-0.01%)	⬇️
..._kernels/maxsim/packed_minmax_x_unpacked_minmax.rs	94.63% <94.63%> (ø)

... and 6 files with indirect coverage changes

🚀 New features to boost your workflow:

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

[Mark Hildebrand (hildebrandmw)]

Thanks Junkui. This is a simplification over the earlier PR! There still is some coupling between the lower-level kernels and some of the higher data preparation stuff.

A few other things that stand out to me:

• It makes heavy use of post-monomorphization errors via const { assert!(...) }. These aren't necessarily wrong, but they are kind of hard to debug when they trigger, don't compose with higher level code well, and to me often indicate that there is another way of structuring the code so they aren't needed. I'm not saying get rid of them, but that over reliance could indicate a missing abstraction.
• Why are 16-wide accumulators used for all architectures? This seems like it could be problematic for Neon or Scalar. Have you checked that the generated code isn't spilling too much and is reasonable?

I know a few other folks are planning on reviewing this as well - let's see what they have to say.

[juchen-ms (partychen)]

Thanks Junkui. This is a simplification over the earlier PR! There still is some coupling between the lower-level kernels and some of the higher data preparation stuff.

A few other things that stand out to me:

• It makes heavy use of post-monomorphization errors via const { assert!(...) }. These aren't necessarily wrong, but they are kind of hard to debug when they trigger, don't compose with higher level code well, and to me often indicate that there is another way of structuring the code so they aren't needed. I'm not saying get rid of them, but that over reliance could indicate a missing abstraction.
• Why are 16-wide accumulators used for all architectures? This seems like it could be problematic for Neon or Scalar. Have you checked that the generated code isn't spilling too much and is reasonable?

I know a few other folks are planning on reviewing this as well - let's see what they have to say.

Thanks for the feedback. I’ve moved SIMD-specific operations behind ExtraWide, removing the lane-count const assertions from the generic microkernel. The arithmetic-safety checks remain.

I’ve also added MR=8 alternatives for Neon, V3, and Scalar’s i16 path rather than requiring 16-wide accumulators everywhere. Earlier V3 assembly inspection showed register-resident accumulators in the full contraction loop, but stack traffic around compensation and tails; I’m not claiming all configurations are spill-free.

PackedA remains pub(crate) for now. I’ll incorporate the other reviewers’ feedback as well.

[Mark Hildebrand (hildebrandmw)]

I still have structural maintenance concerns. The lowering infrastructure either reverifies constraints that the caller should have already established (via asserts), or through slicing, or through tests rather than making the structure easy to follow.

There's also a pretty hefty monomorphization tax for all the different parameters run under test that I'm not thrilled about.

If your team is willing to accept all maintenance associated with this code, I'll sign off.

[juchen-ms (partychen)]

Thanks, Mark. I pushed another cleanup. K now comes from packed A instead of being passed separately, A’s coefficients are prepared per panel, and B reuses the existing unpacked traversal. I also reduced the full-driver test combinations and removed duplicate test setup.

[Mark Hildebrand (hildebrandmw)]

Thanks for your patience - I think there's still a lot of work that can be done within all of matrix_kernels to make these less spooky. But let's unblock the work gated behind this.