Skip to content

Add: radius parameter for distance-bounded search#713

Open
andrea-dagostino wants to merge 1 commit intounum-cloud:mainfrom
andrea-dagostino:feature/radius-search
Open

Add: radius parameter for distance-bounded search#713
andrea-dagostino wants to merge 1 commit intounum-cloud:mainfrom
andrea-dagostino:feature/radius-search

Conversation

@andrea-dagostino
Copy link

Summary

  • The change implements the radius argument for search across the C++ core and Python wrapper, allowing users to exclude results beyond a maximum distance threshold.
  • Adds float radius to index_search_config_t, threaded through index_dense_gt::search() and filtered_search() overloads, with post-sort filtering in index_gt::search().
  • Wires the existing-but-unused radius parameter in Python Index.search() through _search_in_compiled(), and adds it to Indexes.search() and the module-level search().
  • Results with distance > radius are excluded; distance == radius is included. Default is infinity (no filtering, fully backward-compatible).

Changed files

File What
include/usearch/index.hpp radius field in index_search_config_t + filtering after sort_ascending()/shrink()
include/usearch/index_dense.hpp radius param on all 12 search()/filtered_search() overloads + search_()
python/usearch/index.py radius wired through _search_in_compiled(), Index.search(), Indexes.search(), search()
cpp/test.cpp test_radius_search() -- default, tight, zero, and infinite radius with L2sq
python/scripts/test_index.py 4 test functions (11 parametrized cases) covering filtering, defaults, edge cases, single/batch

Design notes

  • C++ filtering happens after HNSW traversal completes (post-filter on sorted results), not during traversal;
  • Python filtering uses np.searchsorted on the ascending-sorted distance arrays in _search_in_compiled(). This handles both the HNSW and brute-force exact search paths without changing lib.cpp;
  • lib.cpp (pybind11 bindings) is intentionally not changed -- the module-level search(exact=True) path forwards **kwargs to _exact_search, which doesn't accept radius. Extracting radius as a named parameter in _search_in_compiled() avoids this cleanly.

Tests

  • C++ test_radius_search() passes (default, tight, zero, infinite radius)
  • C++ full test suite passes (build_debug/test_cpp)
  • Python radius tests pass (11/11 cases)
  • Python full test suite passes (593 passed, 6 skipped -- skips are pre-existing)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant