Promote filtering_rate to base search_params; honor it in brute_force

[maxwbuckley]

Summary

• filtering_rate previously lived on cagra::search_params only. Moving it to the base cuvs::neighbors::search_params makes it inheritable by every algorithm's search_params and removes the duplicate-per-algorithm pattern that would follow if other prefiltered paths wanted the same knob.
• Plumbs brute_force::search_params through detail::search and brute_force_search_filtered. When params.filtering_rate >= 0, the hint is used directly as sparsity and the per-search bitset_view::count(res) popcount + host sync is skipped on the dense path. The sparse CSR path still needs an exact non-zero count to size the matrix, so popcount runs lazily there.
• Algorithms that don't use the hint (ivf_flat, ivf_pq, hnsw) ignore it; their search_params inherit the field but nothing reads it.

Closes #1960.

cc @cjnolet — this is the cleanup for the popcount-per-search overhead from #1960.

Why

Both cagra::search (with default filtering_rate=-1.0) and brute_force::search (always) call bitset_view::count(res) on every search to derive selectivity. That's a GPU reduction kernel + host stream sync per call. Documented measured impact on RTX 5090 at 1M/d=128/50% pass rate is ~18% latency overhead for CAGRA; brute_force had no escape hatch at all because its search_params was an empty derivation of the base.

brute_force::search_params was already empty (struct search_params : cuvs::neighbors::search_params {};), so the field arrives via inheritance — no algorithm-specific addition needed.

What changed

File	Change
cpp/include/cuvs/neighbors/common.hpp	Add float filtering_rate = -1.0 to base search_params with docstring
cpp/include/cuvs/neighbors/cagra.hpp	Remove duplicate field; inherited from base
cpp/src/neighbors/brute_force.cu	Forward params through the 4 macro search() entry points
cpp/src/neighbors/detail/knn_brute_force.cuh	Add params arg to detail::search and brute_force_search_filtered; honor hint when >= 0, lazy popcount on CSR path
cpp/tests/neighbors/brute_force_prefiltered.cu	Add ResultWithFilteringRateHint test cases for bitmap and bitset fixtures (float and half) reusing the existing parameter matrix

Test plan

• cpp/src/neighbors/brute_force.cu compiles cleanly
• cpp/tests/neighbors/brute_force_prefiltered.cu compiles cleanly
• Run NEIGHBORS_TEST to confirm ResultWithFilteringRateHint matches Result across all parameter cases
• Run existing CAGRA tests to confirm no regression from removing the field declaration (inheritance path)

Notes

• ABI: base search_params was sizeof == 1 (empty); now sizeof == 4 (one float). All algorithm-specific search_params inherit, so their layout grows by 4 bytes. Appropriate for a release-cycle change.
• No C/Python binding changes needed — filtering_rate is currently only referenced from C++.
• Behavior identical when filtering_rate < 0 (default): same popcount, same downstream logic.

🤖 Generated with Claude Code

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features

  • Added optional filtering_rate hint parameter to neighbor search operations. Users can now provide a sparsity/selectivity hint to optimize filtered search performance by avoiding unnecessary GPU synchronization and computation.

• Bug Fixes

  • Consolidated filtering_rate field to shared base search parameters to eliminate duplication across search algorithms.

Walkthrough

This PR introduces an optional filtering_rate hint in the base search_params struct to avoid expensive GPU popcount + stream synchronization for filter selectivity auto-detection. CAGRA and brute_force implementations are updated to inherit and thread the hint through, using it to defer exact nnz computation when provided. Tests validate the hint path.

Changes

Filtering Rate Hint Optimization

Layer / File(s)	Summary
Base search_params contract cpp/include/cuvs/neighbors/common.hpp	search_params gains filtering_rate field (default -1.0) with documentation explaining how algorithms use it to skip auto-detecting filter selectivity, avoiding GPU reduction + sync overhead.
CAGRA and brute_force API adoption cpp/include/cuvs/neighbors/cagra.hpp, cpp/src/neighbors/brute_force.cu	CAGRA removes local filtering_rate to inherit from base. Brute_force macro-generated search overloads thread params to detail implementation.
Brute_force detail: hint-based lazy nnz cpp/src/neighbors/detail/knn_brute_force.cuh	brute_force_search_filtered accepts params and uses filtering_rate as hint to defer nnz computation; exact count is computed only when hint is not provided, avoiding popcount cost.
Filtering_rate hint test coverage cpp/tests/neighbors/brute_force_prefiltered.cu	Bitmap and bitset test classes gain RunWithFilteringRateHint() methods that validate search correctness when explicit hint equals test sparsity; new TEST_P registrations cover float and half types.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Suggested labels

improvement, non-breaking

Suggested reviewers

• irina-resh-nvda
• tfeher
• achirkin

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.67% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: promoting filtering_rate from cagra::search_params to the base search_params and implementing its use in brute_force search.
Description check	✅ Passed	The PR description is comprehensive and directly related to the changeset, explaining the motivation, changes, and test plan for moving filtering_rate to base search_params.
Linked Issues check	✅ Passed	The PR addresses the core objective from #1960 by providing a mechanism to skip per-call popcount when filtering_rate >= 0 is pre-set. Changes include: (1) adding filtering_rate to base search_params, (2) implementing the hint in brute_force with lazy popcount on CSR path, (3) adding tests to validate the hint behavior.
Out of Scope Changes check	✅ Passed	All changes align with stated objectives. File modifications are: base search_params API extension, cagra.hpp field removal, brute_force.cu parameter threading, detail/knn_brute_force.cuh hint implementation, and prefiltered tests extension. No unrelated changes detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

cpp/tests/neighbors/brute_force_prefiltered.cu (1)

1084-1130: ⚡ Quick win

Add one high-sparsity hint case to cover the lazy-nnz CSR branch.

Current inputs top out at sparsity = 0.5, so RunWithFilteringRateHint() never exercises the new sparsity >= 0.9 path where exact nnz is computed lazily. Adding at least one > 0.9 case for bitmap and bitset would close this gap.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cpp/tests/neighbors/brute_force_prefiltered.cu` around lines 1084 - 1130, Add
at least one test entry to the selectk_inputs vector that triggers the lazy-nnz
CSR branch by using a sparsity >= 0.9; update the PrefilteredBruteForceInputs
initializer list (selectk_inputs) to include a case with high sparsity (e.g.
0.95) so RunWithFilteringRateHint() exercises the sparsity >= 0.9 path (add one
for bitmap/bitset coverage if your test matrix type selection is driven by the
distance/type field such as cuvs::distance::DistanceType::L2Expanded or
InnerProduct).

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@cpp/src/neighbors/detail/knn_brute_force.cuh`:
- Around line 623-627: The code currently enables hint mode for any non-negative
params.filtering_rate; change this to only enable hint mode when filtering_rate
is in [0.0, 1.0) by replacing the use_hint initialization with an explicit range
check (e.g., const bool use_hint = (params.filtering_rate >= 0.0f &&
params.filtering_rate < 1.0f)); additionally add an explicit validation branch
near that declaration (in the knn_brute_force.cuh scope where use_hint and
params.filtering_rate are used) that treats values >= 1.0f as invalid—either
disable the hint and emit a clear error/exception (e.g., throw
std::invalid_argument or return an error) or log a warning before proceeding—so
out-of-contract inputs do not silently alter path selection.

---

Nitpick comments:
In `@cpp/tests/neighbors/brute_force_prefiltered.cu`:
- Around line 1084-1130: Add at least one test entry to the selectk_inputs
vector that triggers the lazy-nnz CSR branch by using a sparsity >= 0.9; update
the PrefilteredBruteForceInputs initializer list (selectk_inputs) to include a
case with high sparsity (e.g. 0.95) so RunWithFilteringRateHint() exercises the
sparsity >= 0.9 path (add one for bitmap/bitset coverage if your test matrix
type selection is driven by the distance/type field such as
cuvs::distance::DistanceType::L2Expanded or InnerProduct).

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 73fd1e69-bb28-41e6-8152-51e18206fd9f

📥 Commits

Reviewing files that changed from the base of the PR and between 4addf4e and 71decfc.

📒 Files selected for processing (5)

• cpp/include/cuvs/neighbors/cagra.hpp
• cpp/include/cuvs/neighbors/common.hpp
• cpp/src/neighbors/brute_force.cu
• cpp/src/neighbors/detail/knn_brute_force.cuh
• cpp/tests/neighbors/brute_force_prefiltered.cu

[maxwbuckley]

@lowener this is number 2 in my series after 1) the dot product normalization constant optimization and before 3) the scatter gather and threshold fixing

[maxwbuckley]

Pushed ce922ff, which fixes the filtering_rate hint in the prefiltered brute-force tests.

PrefilteredBruteForceInputs::sparsity is the density of kept entries (n_edges = m * n * sparsity, and cpu_convert_to_csr keeps set bits), while search_params::filtering_rate is 1 - nnz / (n_queries * n_dataset). RunWithFilteringRateHint() was passing the former as the latter, so the hint was the complement of the true sparsity. Since the inputs cap out at 0.5 density, every hinted run got a hint below the 0.9 threshold and took the dense path — the lazy-nnz CSR branch was never exercised. It passed anyway because the hint only steers path selection, not correctness.

With the sign fixed, the existing sparsity = 0.01 inputs now hint 0.99 and cover CSR + lazy nnz, while the 0.2/0.4/0.5 inputs still cover dense. That also addresses the CodeRabbit note about missing > 0.9 coverage without adding new inputs, and makes the hint agree with what auto-detection would compute — which is what the method's comment already claimed.

Also bumped the file's SPDX year to 2026; it was the only one of the five touched files still at 2025, so verify-copyright would have failed check-style.

@lowener this PR hasn't had a CI run yet — could I get an /ok to test ce922ff?