vibespatial.kernels.constructive.segmented_union

Segmented union_all kernel: per-group polygon union via GPU tree-reduce.

ADR-0002: CONSTRUCTIVE class – fp64 by design on all devices. ADR-0033: Tier classification – delegates to overlay pipeline (Tier 1 NVRTC

  • Tier 3a CCCL + Tier 2 CuPy) via overlay_union_owned.

ADR-0034: Inherits overlay pipeline precompilation; no new NVRTC source.

Algorithm

For each group defined by group_offsets (CSR-style):

  • size 0: produce empty polygon

  • size 1: pass through unchanged

  • size 2: single pairwise overlay union

  • size N>2: binary-tree reduction in ceil(log2(N)) rounds

Tree reduction intermediates stay device-resident throughout. Final group results are concatenated at the buffer level (no Shapely round-trip) via _concat_owned_arrays.

The overlay pipeline is strictly pairwise (left[i] vs right[i]), so each pair union is a separate GPU dispatch. Groups are iterated serially with GPU parallelism within each overlay_union_owned call.

Attributes

cp

Functions

segmented_union_all(...)

Union all geometries within each group. Returns one geometry per group.

Module Contents

vibespatial.kernels.constructive.segmented_union.cp = None
vibespatial.kernels.constructive.segmented_union.segmented_union_all(geometries: vibespatial.geometry.owned.OwnedGeometryArray, group_offsets: numpy.ndarray, *, dispatch_mode: vibespatial.runtime.ExecutionMode | str = ExecutionMode.AUTO, precision: vibespatial.runtime.precision.PrecisionMode | str = PrecisionMode.AUTO) → vibespatial.geometry.owned.OwnedGeometryArray

Union all geometries within each group. Returns one geometry per group.

Parameters

geometriesOwnedGeometryArray

Input polygons (device- or host-resident).

group_offsetsarray-like

CSR-style int32/int64 offsets. Group i contains geometries[group_offsets[i]:group_offsets[i+1]]. Length is n_groups + 1.

dispatch_modeExecutionMode or str

Execution mode hint (AUTO, GPU, CPU).

precisionPrecisionMode or str

Precision mode. CONSTRUCTIVE kernels stay fp64 per ADR-0002.

Returns

OwnedGeometryArray

One geometry per group. May contain MultiPolygon when union produces disconnected regions. Empty groups produce empty Polygon.