Add custom eigensolver (Block Krylov-Schur algorithm)

[Suhas Jayaram Subramanya (suhasjs)]

• 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?

Reference Issues/PRs

Multi-vector indexing support -- #1019

N/A

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

Implements a new custom eigensolver to compute top-k (eigenvalue, eigenvector) pairs (ordered desc by magnitude of eigenvalue). This solver is a faer-based Rust port of the Block Krylov-Schur algorithm implemented in microsoft/ISLE. Restarted Block Krylov-Schur only needs access to a matrix-vector dot-product operator and can be orders of magnitude more efficient than simply calling ARPACK/LAPACK's gesvd for large sparse matrices.
On benchmarks with real multi-vectors, this algorithm was an order of magnitude quicker than faer's compute_evd_real primarily because it allows us to configure the 'convergence' threshold and does not require computing all (eigenvalue,eigenvector) pairs (early-exits if top-wanted pairs have converged).

Changes are restricted to diskann-linalg crate. The new eigensolver is available under diskann_linalg::block_krylov_schur module.

Highlights:

• SymmetricOperator: a trait to supply the matrix-vector product through SymmetricOperator::apply. This PR provides three symmetric operator implementations for (a) any f32 matrix A of shape N x N, (b) AA^T for a f32 matrix with shape M x N, and (c) A^T A for shape N x M.
• BlockKrylovSchurParams holds inputs to the algorithm, BlockKrylovSchurResult the outputs, and BlockKrylovSchurError is crate-supplied error type
• Solver<Operator> struct to manage state for algorithm, and block_krylov_schur_eigenpairs_with_progress function to automatically create a Solver using a SymmetricOperator and BlockKrylovSchurParams, and extract out top wanted (eigenvalue, eigenvector) pairs into a BlockKrylovSchurResult (or propagate BlockKrylovSchurError if necessary).
• Tests for tall-skinny, short-wide, and square matrices up-to 1024-dimension on the longest side (compared to faer eigenvalue decomposition), along with input validation errors and known algorithm failure modes.

Any other comments?

[Copilot]

🟡 Changes recommended

The solver can panic due to non-block-aligned convergence locking interacting with minimal ncv settings, and this needs to be fixed before merging.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR adds a new diskann_linalg::block_krylov_schur module implementing a restarted Block Krylov–Schur eigensolver for real symmetric operators, including built-in row-major operator adapters (dense symmetric, AᵀA, and AAᵀ). This expands diskann-linalg with an efficient top-k eigenpair routine suitable for large operators exposed via matrix–vector products.

Changes:

• Expose a new block_krylov_schur public module from diskann-linalg.
• Add the Block Krylov–Schur solver implementation, operator traits/adapters, parameter/result/error types, and extensive tests.
• Provide progress reporting and a helper to compute an upper bound on operator applications.

File summaries

File	Description
diskann-linalg/src/lib.rs	Re-exports the new block_krylov_schur module.
diskann-linalg/src/block_krylov_schur.rs	Implements the eigensolver, built-in operators, and associated tests.

Review details

Suppressed comments (1)

diskann-linalg/src/block_krylov_schur.rs:891

• After introducing a separate converged counter (so the internal locked prefix can remain block-aligned), the result should report the exact converged pair count rather than the internal s.conv (which is block-aligned and may under-report).

 eigenvectors: out,
status,
converged: s.conv,
iterations: s.iters,
block_operator_applications: s.apps,

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 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 93.21534% with 69 lines in your changes missing coverage. Please review.
✅ Project coverage is 91.44%. Comparing base (600c2b9) to head (844f0d8).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
diskann-linalg/src/block_krylov_schur.rs	93.21%	69 Missing ⚠️

Additional details and impacted files

@@ Coverage Diff @@## main #1383 +/- ##
==========================================
- Coverage 91.55% 91.44% -0.11% 
==========================================
Files 521 522 +1 Lines 100302 101743 +1441 ==========================================
+ Hits 91828 93036 +1208 - Misses 8474 8707 +233 

Flag	Coverage Δ
miri	91.44% <93.21%> (-0.11%)	⬇️
unittests	91.24% <93.21%> (+<0.01%)	⬆️

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

Files with missing lines	Coverage Δ
diskann-linalg/src/lib.rs	99.69% <ø> (ø)
diskann-linalg/src/block_krylov_schur.rs	93.21% <93.21%> (ø)

... and 42 files with indirect coverage changes

🚀 New features to boost your workflow:

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