vibespatial.spatial.indexing¶

Attributes¶

`cp`
`logger`

Classes¶

`CandidatePairs`	MBR candidate pair result with optional device-resident arrays.
`BoundsPairBenchmark`
`FlatSpatialIndex`
`RegularGridRectIndex`
`SegmentMBRTable`	Segment MBR table with optional device-resident arrays.
`SegmentCandidatePairs`	Segment candidate pairs with lazy device-to-host materialization.
`SegmentFilterBenchmark`

Functions¶

`generate_bounds_pairs`(→ CandidatePairs)
`benchmark_bounds_pairs`(→ BoundsPairBenchmark)
`build_flat_spatial_index`(→ FlatSpatialIndex)
`extract_segment_mbrs`(→ SegmentMBRTable)	Extract per-segment MBRs from all line/polygon geometries.
`generate_segment_mbr_pairs`(→ SegmentCandidatePairs)	Generate candidate segment pairs by MBR overlap filtering.
`benchmark_segment_filter`(→ SegmentFilterBenchmark)

Module Contents¶

vibespatial.spatial.indexing.cp = None¶

vibespatial.spatial.indexing.logger¶

class vibespatial.spatial.indexing.CandidatePairs¶

MBR candidate pair result with optional device-resident arrays.

When produced by the GPU path, _device_left_indices and _device_right_indices hold CuPy device arrays. The public left_indices and right_indices properties lazily materialise host (NumPy) arrays on first access, following the same pattern as FlatSpatialIndex.

left_bounds: numpy.ndarray¶

right_bounds: numpy.ndarray¶

pairs_examined: int¶

tile_size: int¶

same_input: bool¶

property left_indices: numpy.ndarray¶: Lazily materialise host left_indices from device (ADR-0005).

property right_indices: numpy.ndarray¶: Lazily materialise host right_indices from device (ADR-0005).

property device_left_indices¶: CuPy device array of left indices, or None if CPU-produced.

property device_right_indices¶: CuPy device array of right indices, or None if CPU-produced.

property count: int¶

vibespatial.spatial.indexing.generate_bounds_pairs(left: vibespatial.geometry.owned.OwnedGeometryArray, right: vibespatial.geometry.owned.OwnedGeometryArray | None = None, *, tile_size: int = 256, include_self: bool = False) → CandidatePairs¶

class vibespatial.spatial.indexing.BoundsPairBenchmark¶

dataset: str¶

rows: int¶

tile_size: int¶

elapsed_seconds: float¶

pairs_examined: int¶

candidate_pairs: int¶

vibespatial.spatial.indexing.benchmark_bounds_pairs(geometry_array: vibespatial.geometry.owned.OwnedGeometryArray, *, dataset: str, tile_size: int = 256) → BoundsPairBenchmark¶

class vibespatial.spatial.indexing.FlatSpatialIndex¶

geometry_array: vibespatial.geometry.owned.OwnedGeometryArray¶

bounds: numpy.ndarray¶

total_bounds: tuple[float, float, float, float]¶

regular_grid: RegularGridRectIndex | None = None¶

device_morton_keys: object = None¶

device_order: object = None¶

property order: numpy.ndarray¶: Lazily materialise host order array from device (ADR-0005).

property morton_keys: numpy.ndarray¶: Lazily materialise host morton_keys array from device (ADR-0005).

property size: int¶

query_bounds(bounds: tuple[float, float, float, float]) → numpy.ndarray¶

query(other: vibespatial.geometry.owned.OwnedGeometryArray, *, tile_size: int = 256) → CandidatePairs¶

class vibespatial.spatial.indexing.RegularGridRectIndex¶

origin_x: float¶

origin_y: float¶

cell_width: float¶

cell_height: float¶

cols: int¶

rows: int¶

size: int¶

vibespatial.spatial.indexing.build_flat_spatial_index(geometry_array: vibespatial.geometry.owned.OwnedGeometryArray, *, runtime_selection: vibespatial.runtime.RuntimeSelection | None = None) → FlatSpatialIndex¶

class vibespatial.spatial.indexing.SegmentMBRTable¶

Segment MBR table with optional device-resident arrays.

When produced by the GPU path, arrays are CuPy device arrays and residency is Residency.DEVICE. The public properties row_indices, segment_indices, and bounds return the underlying arrays as-is (device or host). Use to_host() to get a copy with NumPy arrays on the host side.

row_indices: object¶

segment_indices: object¶

bounds: object¶

residency: vibespatial.runtime.residency.Residency¶

property count: int¶

to_host() → SegmentMBRTable¶

Return a host-resident copy (NumPy arrays).

If already host-resident, returns self.

vibespatial.spatial.indexing.extract_segment_mbrs(geometry_array: vibespatial.geometry.owned.OwnedGeometryArray) → SegmentMBRTable¶

Extract per-segment MBRs from all line/polygon geometries.

Dispatches to GPU when available, falling back to CPU otherwise. The GPU path returns device-resident CuPy arrays (no D->H transfer).

class vibespatial.spatial.indexing.SegmentCandidatePairs¶

Segment candidate pairs with lazy device-to-host materialization.

When produced by the GPU path, _device_* fields hold CuPy device arrays and _host_* fields are None. The public properties lazily call cp.asnumpy() on first host access, following the CandidatePairs pattern (ADR-0005).

pairs_examined: int¶

property left_rows: numpy.ndarray¶: Lazily materialise host left_rows from device (ADR-0005).

property left_segments: numpy.ndarray¶: Lazily materialise host left_segments from device (ADR-0005).

property right_rows: numpy.ndarray¶: Lazily materialise host right_rows from device (ADR-0005).

property right_segments: numpy.ndarray¶: Lazily materialise host right_segments from device (ADR-0005).

property device_left_rows¶: CuPy device array of left row indices, or None if CPU-produced.

property device_left_segments¶: CuPy device array of left segment indices, or None if CPU-produced.

property device_right_rows¶: CuPy device array of right row indices, or None if CPU-produced.

property device_right_segments¶: CuPy device array of right segment indices, or None if CPU-produced.

property count: int¶

vibespatial.spatial.indexing.generate_segment_mbr_pairs(left: vibespatial.geometry.owned.OwnedGeometryArray, right: vibespatial.geometry.owned.OwnedGeometryArray, *, tile_size: int = 512) → SegmentCandidatePairs¶

Generate candidate segment pairs by MBR overlap filtering.

Dispatches to GPU when available. The GPU path uses the existing sweep-sort overlap kernel (_generate_bounds_pairs_gpu) on segment bounds, returning device-resident CuPy arrays (no eager D->H transfer).

class vibespatial.spatial.indexing.SegmentFilterBenchmark¶

rows_left: int¶

rows_right: int¶

naive_segment_pairs: int¶

filtered_segment_pairs: int¶

elapsed_seconds: float¶

vibespatial.spatial.indexing.benchmark_segment_filter(left: vibespatial.geometry.owned.OwnedGeometryArray, right: vibespatial.geometry.owned.OwnedGeometryArray, *, tile_size: int = 512) → SegmentFilterBenchmark¶