vibespatial.predicates.relate

GPU-accelerated DE-9IM relate computation.

Computes the full 9-Intersection Model matrix per geometry pair, returning a 9-character string like “212101212” per pair. Mirrors shapely.relate().

Strategy:

GPU kernels handle the common Point-* family combinations where the DE-9IM matrix is deterministic from point location classification:

• Point-Point: equality check -> one of two fixed matrices

• Point-LineString/MultiLineString: location on line -> fixed matrix

• Point-Polygon/MultiPolygon: PIP classification -> fixed matrix

For non-point families (Line-Line, Line-Polygon, Polygon-Polygon), the existing polygon.py DE-9IM bitmask kernel computes presence/absence of each cell but NOT the dimension (which is needed for the string). These fall back to Shapely.

Tier classification per ADR-0033:

• Point-* GPU paths: reuse existing Tier 1 NVRTC kernels from point_relations.py (geometry-specific inner loops).

• Non-point: Shapely fallback with record_fallback_event.

ADR-0002: PREDICATE kernel class. Point-* kernels inherit precision compliance from the underlying point_relations infrastructure.

Attributes

logger

Functions

relate_de9im(→ numpy.ndarray)	Compute the DE-9IM intersection matrix for each pair of geometries.
relate_pattern_match(→ numpy.ndarray)	Check if the DE-9IM relationship matches a pattern for each pair.

Module Contents

vibespatial.predicates.relate.logger

vibespatial.predicates.relate.relate_de9im(left: vibespatial.geometry.owned.OwnedGeometryArray, right: vibespatial.geometry.owned.OwnedGeometryArray, *, dispatch_mode: vibespatial.runtime.ExecutionMode | str = ExecutionMode.AUTO, precision: vibespatial.runtime.precision.PrecisionMode | str = PrecisionMode.AUTO) → numpy.ndarray

Compute the DE-9IM intersection matrix for each pair of geometries.

Parameters

left, rightOwnedGeometryArray

Pairwise-aligned geometry arrays. Must have the same row_count.

dispatch_modeExecutionMode

Requested execution mode (AUTO, GPU, CPU).

precisionPrecisionMode

Precision mode for GPU kernels (AUTO, FP32, FP64).

Returns

np.ndarray

Object array of 9-character DE-9IM strings (or None for null pairs). Shape (row_count,).

Notes

GPU path handles Point-* family combinations. All other combinations fall back to Shapely with a recorded fallback event. Null geometries produce None (not “FFFFFFFFF”) to match Shapely convention.

vibespatial.predicates.relate.relate_pattern_match(left: vibespatial.geometry.owned.OwnedGeometryArray, right: vibespatial.geometry.owned.OwnedGeometryArray, pattern: str, *, dispatch_mode: vibespatial.runtime.ExecutionMode | str = ExecutionMode.AUTO, precision: vibespatial.runtime.precision.PrecisionMode | str = PrecisionMode.AUTO) → numpy.ndarray

Check if the DE-9IM relationship matches a pattern for each pair.

This is the GPU-accelerated equivalent of shapely.relate_pattern(). It computes the full DE-9IM matrix via relate_de9im and then applies the pattern match on the resulting strings.

Parameters

left, rightOwnedGeometryArray

Pairwise-aligned geometry arrays. Must have the same row_count.

patternstr

9-character DE-9IM pattern. Valid characters are: T (matches 0, 1, 2), F (matches F), * (matches any), 0, 1, 2 (exact dimension match).

dispatch_modeExecutionMode

Requested execution mode (AUTO, GPU, CPU).

precisionPrecisionMode

Precision mode for GPU kernels (AUTO, FP32, FP64).

Returns

np.ndarray

Boolean array of shape (row_count,). True where the DE-9IM string matches the pattern, False otherwise. Null geometry pairs produce False.