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¶

`prefers_pair_mask_spatial_index_query`(→ bool)	Return True when device pair-mask query is the preferred physical shape.
`spatial_index_device_query`(...)	GPU-accelerated spatial index query — replaces CPU STRtree traversal.
`spatial_index_device_left_semijoin_rows`(...)	Reduce a dense Morton candidate stream directly into matched rows.
`spatial_index_device_left_match_counts`(...)	Reduce a dense Morton candidate stream directly into int64 counts.
`spatial_index_device_right_semijoin_rows`(...)	Reduce a dense Morton candidate stream into matched indexed rows.
`spatial_index_device_right_match_counts`(...)	Reduce a dense Morton candidate stream into indexed-row counts.
`spatial_index_device_right_pair_match_counts`(...)	Reduce first and aligned shared matches into indexed-row counts.

Module Contents¶

vibespatial.spatial.spatial_index_device.cp = None¶

vibespatial.spatial.spatial_index_device.prefers_pair_mask_spatial_index_query(query_count: int, tree_count: int) → bool¶: Return True when device pair-mask query is the preferred physical shape.

vibespatial.spatial.spatial_index_device.spatial_index_device_query(flat_index, query_bounds, *, native_index=None, distance: numpy.ndarray | object | None = None, precision: vibespatial.runtime.precision.PrecisionMode | str = PrecisionMode.AUTO, allow_bbox_superset: bool = False) → 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.

vibespatial.spatial.spatial_index_device.spatial_index_device_left_semijoin_rows(flat_index, query_owned, tree_owned, query_bounds, *, predicate: str | None, distance: numpy.ndarray | object | None = None, native_index=None) → tuple[object | None, vibespatial.spatial.query_types.SpatialQueryExecution]¶: Reduce a dense Morton candidate stream directly into matched rows.

vibespatial.spatial.spatial_index_device.spatial_index_device_left_match_counts(flat_index, query_owned, tree_owned, query_bounds, *, predicate: str | None, distance: numpy.ndarray | object | None = None, native_index=None) → tuple[object | None, vibespatial.spatial.query_types.SpatialQueryExecution]¶: Reduce a dense Morton candidate stream directly into int64 counts.

vibespatial.spatial.spatial_index_device.spatial_index_device_right_semijoin_rows(flat_index, query_owned, tree_owned, query_bounds, *, predicate: str | None, distance: numpy.ndarray | object | None = None, native_index=None) → tuple[object | None, vibespatial.spatial.query_types.SpatialQueryExecution]¶: Reduce a dense Morton candidate stream into matched indexed rows.

vibespatial.spatial.spatial_index_device.spatial_index_device_right_match_counts(flat_index, query_owned, tree_owned, query_bounds, *, predicate: str | None, distance: numpy.ndarray | object | None = None, native_index=None) → tuple[object | None, vibespatial.spatial.query_types.SpatialQueryExecution]¶: Reduce a dense Morton candidate stream into indexed-row counts.

vibespatial.spatial.spatial_index_device.spatial_index_device_right_pair_match_counts(flat_index, aligned_native_index, query_owned, tree_owned, aligned_tree_owned, query_bounds, *, predicate: str, native_index=None) → tuple[object | None, vibespatial.spatial.query_types.SpatialQueryExecution]¶: Reduce first and aligned shared matches into indexed-row counts.