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¶

`compact_indexed_spatial_input`(...)	Compact variable-width row views at a spatial-consumer boundary.
`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¶

vibespatial.spatial.indexing.compact_indexed_spatial_input(owned: vibespatial.geometry.owned.OwnedGeometryArray) → vibespatial.geometry.owned.OwnedGeometryArray¶

Compact variable-width row views at a spatial-consumer boundary.

Polygonal and other variable-width selections deliberately remain cheap row-indirection views through ordinary dataframe operations. Spatial indexing and exact predicate preparation, however, are shaped by the selected rows rather than by the ancestral coordinate capacity. Resolve that row map once on device before those consumers size coordinate-shaped work. Fixed-width carriers keep their row-indirection form.

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: object¶

right_bounds: object¶

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 device_selection¶: Capacity selection when pair cardinality remains device-resident.

property count: int¶

vibespatial.spatial.indexing.generate_bounds_pairs(left: vibespatial.geometry.owned.OwnedGeometryArray, right: vibespatial.geometry.owned.OwnedGeometryArray | None = None, *, tile_size: int = COARSE_BOUNDS_TILE_SIZE, include_self: bool = False, requested_mode: vibespatial.runtime.ExecutionMode | str = ExecutionMode.AUTO, capacity_output: 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 = COARSE_BOUNDS_TILE_SIZE) → BoundsPairBenchmark¶

class vibespatial.spatial.indexing.FlatSpatialIndex¶

geometry_array: vibespatial.geometry.owned.OwnedGeometryArray¶

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

regular_grid: RegularGridRectIndex | None = None¶

device_morton_keys: object = None¶

device_order: object = None¶

device_bounds: object = None¶

point_grid: object = None¶

property bounds: numpy.ndarray¶: Lazily materialise host bounds for CPU/public compatibility paths.

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¶

geometry_metadata(*, source_token: str | None = None)¶: Wrap index bounds/metadata as a private native carrier.

to_native_spatial_index(*, source_token: str | None = None)¶: Wrap this index as reusable private native execution state.

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

query(other: vibespatial.geometry.owned.OwnedGeometryArray, *, tile_size: int = COARSE_BOUNDS_TILE_SIZE) → 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, device_bounds_only: bool = False) → 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 = SEGMENT_TILE_SIZE) → 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 = SEGMENT_TILE_SIZE) → SegmentFilterBenchmark¶