vibespatial.spatial.spatial_index_device

Device-side spatial index query — unified GPU BVH-style traversal.

Provides spatial_index_device_query, the single entry point for GPU- accelerated spatial index traversal in sjoin and other bulk query paths.

Strategy selection (transparent to caller):

  • Brute-force O(N*M): each query thread scans all tree rows. Optimal when M is small or the total work (N*M) fits in a few waves.

  • Morton range O(N*log(M)+K): uses pre-sorted Morton keys with CCCL binary search to narrow the scan range per query, then refines with bbox overlap. Better for large M where most tree rows are distant.

ADR-0002: COARSE kernel class — bbox comparisons stay fp64 (bounds kernels are memory-bound, not compute-bound, so fp32 provides no throughput advantage, and fp32 rounding could shrink bounds causing false negatives).

ADR-0033 tier classification:

  • Tier 1 (NVRTC): bbox overlap count/scatter, Morton range computation

  • Tier 3a (CCCL): exclusive_sum, lower_bound, upper_bound, compact_indices

Attributes

cp

Functions

spatial_index_device_query(...)

GPU-accelerated spatial index query — replaces CPU STRtree traversal.

Module Contents

vibespatial.spatial.spatial_index_device.cp = None
vibespatial.spatial.spatial_index_device.spatial_index_device_query(flat_index, query_bounds, *, distance: numpy.ndarray | object | None = None, precision: vibespatial.runtime.precision.PrecisionMode | str = PrecisionMode.AUTO) → tuple[vibespatial.spatial.query_types._DeviceCandidates | None, vibespatial.spatial.query_types.SpatialQueryExecution]

GPU-accelerated spatial index query — replaces CPU STRtree traversal.

Parameters

flat_indexFlatSpatialIndex

Pre-built spatial index with Morton keys and sorted order.

query_boundsnp.ndarray, shape (N, 4)

Query bounding boxes as [minx, miny, maxx, maxy] rows.

distancenp.ndarray or None

Per-row distance expansion for dwithin queries. When provided, query bounds are expanded by the corresponding distance before bbox overlap testing.

precisionPrecisionMode

Precision mode override. COARSE class — bounds stay fp64 on all devices (memory-bound; fp32 rounding causes false negatives).

Returns

(candidates, execution)tuple[_DeviceCandidates | None, SpatialQueryExecution]

candidates is None when GPU dispatch is skipped. When GPU dispatch runs and finds no pairs, candidates is an empty device-resident result. execution carries the dispatch decision metadata.