vibespatial.overlay.types¶

Shared overlay pipeline data structures.

Extracted from overlay_gpu.py so that multiple modules (overlay_gpu, make_valid_gpu) can import lightweight data structures without pulling in the full overlay pipeline and its CUDA kernel strings.

Phase 8 (vibeSpatial-p23.8): All four overlay data structures are device-primary with lazy host materialization. GPU-only consumers never trigger D->H copies.

Classes¶

`SplitEventDeviceState`
`SplitEventTable`	Split event table with lazy host materialization.
`AtomicEdgeDeviceState`
`AtomicEdgeTable`	Atomic edge table with lazy host materialization.
`EndpointIncidenceDeviceState`	Exact endpoint grouping and node-incidence CSR on device.
`HalfEdgeGraphDeviceState`
`HalfEdgeGraph`	Half-edge graph with device-primary storage and lazy host materialization.
`OverlayFaceDeviceState`
`GpuFaceWalkResult`	Device face-walk result with a backward-compatible unpacking surface.
`IndexedComponentContainmentDeviceState`	Fixed-capacity indexed containment metadata for face components.
`OverlayFaceTable`
`OverlayExecutionPlan`	Reusable overlay topology plan for one left/right workload.
`ComponentOverlayExecutionPlan`	One oversized logical row decomposed into disjoint topology rows.
`MicrocellOverlayExecutionPlan`	One connected oversized row reconstructed from paged microcell bands.
`PagedOverlayExecutionPlan`	Independent row-isolated topology plans bounded by live-event work.

Module Contents¶

class vibespatial.overlay.types.SplitEventDeviceState¶

source_segment_ids: vibespatial.cuda._runtime.DeviceArray¶

t: vibespatial.cuda._runtime.DeviceArray¶

x: vibespatial.cuda._runtime.DeviceArray¶

y: vibespatial.cuda._runtime.DeviceArray¶

source_side: vibespatial.cuda._runtime.DeviceArray | None = None¶

row_indices: vibespatial.cuda._runtime.DeviceArray | None = None¶

part_indices: vibespatial.cuda._runtime.DeviceArray | None = None¶

ring_indices: vibespatial.cuda._runtime.DeviceArray | None = None¶

geometry_indices: vibespatial.cuda._runtime.DeviceArray | None = None¶

planarity_risk: vibespatial.cuda._runtime.DeviceArray | None = None¶

class vibespatial.overlay.types.SplitEventTable¶

Split event table with lazy host materialization.

When produced by the GPU pipeline, all arrays live in device_state and host numpy arrays are lazily copied on first property access. GPU-only consumers that read only device_state, count, left_segment_count, right_segment_count, and runtime_selection never trigger device-to-host copies.

left_segment_count: int¶

right_segment_count: int¶

runtime_selection: vibespatial.runtime.RuntimeSelection¶

device_state: SplitEventDeviceState¶

requires_renoding: bool = False¶

property source_segment_ids: numpy.ndarray¶

property source_side: numpy.ndarray¶

property row_indices: numpy.ndarray¶

property part_indices: numpy.ndarray¶

property ring_indices: numpy.ndarray¶

property t: numpy.ndarray¶

property x: numpy.ndarray¶

property y: numpy.ndarray¶

property count: int¶

class vibespatial.overlay.types.AtomicEdgeDeviceState¶

source_segment_ids: vibespatial.cuda._runtime.DeviceArray¶

direction: vibespatial.cuda._runtime.DeviceArray¶

src_x: vibespatial.cuda._runtime.DeviceArray¶

src_y: vibespatial.cuda._runtime.DeviceArray¶

dst_x: vibespatial.cuda._runtime.DeviceArray¶

dst_y: vibespatial.cuda._runtime.DeviceArray¶

row_indices: vibespatial.cuda._runtime.DeviceArray | None = None¶

part_indices: vibespatial.cuda._runtime.DeviceArray | None = None¶

ring_indices: vibespatial.cuda._runtime.DeviceArray | None = None¶

source_side: vibespatial.cuda._runtime.DeviceArray | None = None¶

source_membership: vibespatial.cuda._runtime.DeviceArray | None = None¶

tangent_x: vibespatial.cuda._runtime.DeviceArray | None = None¶

tangent_y: vibespatial.cuda._runtime.DeviceArray | None = None¶

left_coverage_delta: vibespatial.cuda._runtime.DeviceArray | None = None¶

right_coverage_delta: vibespatial.cuda._runtime.DeviceArray | None = None¶

planarity_risk: vibespatial.cuda._runtime.DeviceArray | None = None¶

class vibespatial.overlay.types.AtomicEdgeTable¶

Atomic edge table with lazy host materialization.

Host numpy arrays are lazily copied from device_state on first access, matching the HalfEdgeGraph lazy pattern. GPU-only consumers that read only device_state, count, left_segment_count, right_segment_count, and runtime_selection never trigger the device-to-host copies.

left_segment_count: int¶

right_segment_count: int¶

runtime_selection: vibespatial.runtime.RuntimeSelection¶

device_state: AtomicEdgeDeviceState¶

property source_segment_ids: numpy.ndarray¶

property source_side: numpy.ndarray¶

property row_indices: numpy.ndarray¶

property part_indices: numpy.ndarray¶

property ring_indices: numpy.ndarray¶

property direction: numpy.ndarray¶

property src_x: numpy.ndarray¶

property src_y: numpy.ndarray¶

property dst_x: numpy.ndarray¶

property dst_y: numpy.ndarray¶

property count: int¶

class vibespatial.overlay.types.EndpointIncidenceDeviceState¶

Exact endpoint grouping and node-incidence CSR on device.

incidence_edge_ids stores outgoing half-edge ids grouped by exact endpoint (and optionally source row). node_offsets has edge-capacity storage; node_count is a one-element device scalar delimiting its live prefix. Keeping this state separate from radial ordering lets topology consumers peel or classify the graph without first building successors.

incidence_edge_ids: vibespatial.cuda._runtime.DeviceArray¶

node_offsets: vibespatial.cuda._runtime.DeviceArray¶

src_node_ids: vibespatial.cuda._runtime.DeviceArray¶

node_count: vibespatial.cuda._runtime.DeviceArray¶

edge_count: int¶

isolate_rows: bool = False¶

class vibespatial.overlay.types.HalfEdgeGraphDeviceState¶

node_x: vibespatial.cuda._runtime.DeviceArray | None¶

node_y: vibespatial.cuda._runtime.DeviceArray | None¶

src_node_ids: vibespatial.cuda._runtime.DeviceArray | None¶

dst_node_ids: vibespatial.cuda._runtime.DeviceArray | None¶

angle: vibespatial.cuda._runtime.DeviceArray | None¶

sorted_edge_ids: vibespatial.cuda._runtime.DeviceArray | None¶

edge_positions: vibespatial.cuda._runtime.DeviceArray | None¶

next_edge_ids: vibespatial.cuda._runtime.DeviceArray¶

src_x: vibespatial.cuda._runtime.DeviceArray¶

src_y: vibespatial.cuda._runtime.DeviceArray¶

source_segment_ids: vibespatial.cuda._runtime.DeviceArray | None = None¶

source_side: vibespatial.cuda._runtime.DeviceArray | None = None¶

source_membership: vibespatial.cuda._runtime.DeviceArray | None = None¶

row_indices: vibespatial.cuda._runtime.DeviceArray | None = None¶

part_indices: vibespatial.cuda._runtime.DeviceArray | None = None¶

ring_indices: vibespatial.cuda._runtime.DeviceArray | None = None¶

direction: vibespatial.cuda._runtime.DeviceArray | None = None¶

left_coverage_delta: vibespatial.cuda._runtime.DeviceArray | None = None¶

right_coverage_delta: vibespatial.cuda._runtime.DeviceArray | None = None¶

class vibespatial.overlay.types.HalfEdgeGraph¶

Half-edge graph with device-primary storage and lazy host materialization.

All arrays (both topology and per-edge metadata) are stored on device via device_state and lazily copied to host on first property access. GPU-only consumers that read device_state, edge_count, node_count, left_segment_count, right_segment_count, and runtime_selection never trigger device-to-host copies.

left_segment_count: int¶

right_segment_count: int¶

runtime_selection: vibespatial.runtime.RuntimeSelection¶

device_state: HalfEdgeGraphDeviceState¶

isolate_rows: bool = False¶

property source_segment_ids: numpy.ndarray¶

property source_side: numpy.ndarray¶

property row_indices: numpy.ndarray¶

property part_indices: numpy.ndarray¶

property ring_indices: numpy.ndarray¶

property direction: numpy.ndarray¶

property src_x: numpy.ndarray¶

property src_y: numpy.ndarray¶

property dst_x: numpy.ndarray¶

property dst_y: numpy.ndarray¶

property node_x: numpy.ndarray¶

property node_y: numpy.ndarray¶

property src_node_ids: numpy.ndarray¶

property dst_node_ids: numpy.ndarray¶

property angle: numpy.ndarray¶

property sorted_edge_ids: numpy.ndarray¶

property edge_positions: numpy.ndarray¶

property next_edge_ids: numpy.ndarray¶

property edge_count: int¶

property node_count: int¶

class vibespatial.overlay.types.OverlayFaceDeviceState¶

face_offsets: vibespatial.cuda._runtime.DeviceArray¶

face_edge_ids: vibespatial.cuda._runtime.DeviceArray¶

edge_face_ids: vibespatial.cuda._runtime.DeviceArray¶

bounded_mask: vibespatial.cuda._runtime.DeviceArray¶

signed_area: vibespatial.cuda._runtime.DeviceArray¶

centroid_x: vibespatial.cuda._runtime.DeviceArray¶

centroid_y: vibespatial.cuda._runtime.DeviceArray¶

left_covered: vibespatial.cuda._runtime.DeviceArray¶

right_covered: vibespatial.cuda._runtime.DeviceArray¶

cycle_orientation: vibespatial.cuda._runtime.DeviceArray | None = None¶

class vibespatial.overlay.types.GpuFaceWalkResult¶

Device face-walk result with a backward-compatible unpacking surface.

Existing shared callers unpack the historical eight fields. Exact overlay consumers additionally read cycle_orientation without forcing those callers to change in lockstep.

face_offsets: vibespatial.cuda._runtime.DeviceArray¶

face_edge_ids: vibespatial.cuda._runtime.DeviceArray¶

edge_face_ids: vibespatial.cuda._runtime.DeviceArray¶

bounded_mask: vibespatial.cuda._runtime.DeviceArray¶

signed_area: vibespatial.cuda._runtime.DeviceArray¶

centroid_x: vibespatial.cuda._runtime.DeviceArray¶

centroid_y: vibespatial.cuda._runtime.DeviceArray¶

face_count: int¶

cycle_orientation: vibespatial.cuda._runtime.DeviceArray¶

class vibespatial.overlay.types.IndexedComponentContainmentDeviceState¶

Fixed-capacity indexed containment metadata for face components.

Negative roots occupy face-capacity lanes with -1 sentinels. Positive candidate faces are min-X sorted into the same capacity and indexed by an interval max-X tree. Device reductions fill winding baselines, containment depth, and the structurally immediate parent without materializing a compact pair relation or crossing a host allocation fence.

face_component: vibespatial.cuda._runtime.DeviceArray¶

face_bounds: vibespatial.cuda._runtime.DeviceArray¶

root_faces: vibespatial.cuda._runtime.DeviceArray¶

candidate_faces: vibespatial.cuda._runtime.DeviceArray¶

interval_max_x: vibespatial.cuda._runtime.DeviceArray¶

left_baseline: vibespatial.cuda._runtime.DeviceArray¶

right_baseline: vibespatial.cuda._runtime.DeviceArray¶

component_depth: vibespatial.cuda._runtime.DeviceArray¶

component_parent: vibespatial.cuda._runtime.DeviceArray | None¶

face_capacity: int¶

leaf_count: int¶

transient_owners: tuple[object, Ellipsis] = ()¶

class vibespatial.overlay.types.OverlayFaceTable¶

runtime_selection: vibespatial.runtime.RuntimeSelection¶

device_state: OverlayFaceDeviceState¶

property face_offsets: numpy.ndarray¶

property face_edge_ids: numpy.ndarray¶

property bounded_mask: numpy.ndarray¶

property signed_area: numpy.ndarray¶

property cycle_orientation: numpy.ndarray¶

property centroid_x: numpy.ndarray¶

property centroid_y: numpy.ndarray¶

property left_covered: numpy.ndarray¶

property right_covered: numpy.ndarray¶

property face_count: int¶

class vibespatial.overlay.types.OverlayExecutionPlan¶

Reusable overlay topology plan for one left/right workload.

split_events: SplitEventTable | None¶

atomic_edges: AtomicEdgeTable | None¶

half_edge_graph: HalfEdgeGraph¶

faces: OverlayFaceTable¶

row_isolated: bool = False¶

class vibespatial.overlay.types.ComponentOverlayExecutionPlan¶

One oversized logical row decomposed into disjoint topology rows.

left and right contain aligned synthetic MultiPolygon rows. Their combined polygon-part x intervals are strictly separated between rows, so each row owns an independent face graph and the results can be packed back into one geometry without another constructive union.

left: object¶

right: object¶

component_count: int¶

max_left_segments_per_component: int¶

max_right_segments_per_component: int¶

dispatch_mode: object¶

include_same_side_splits: bool = False¶

row_isolated: bool = True¶

class vibespatial.overlay.types.MicrocellOverlayExecutionPlan¶

One connected oversized row reconstructed from paged microcell bands.

left: object¶

right: object¶

max_left_segments: int¶

max_right_segments: int¶

dispatch_mode: object¶

row_isolated: bool = True¶

class vibespatial.overlay.types.PagedOverlayExecutionPlan¶

Independent row-isolated topology plans bounded by live-event work.

Every page owns complete logical rows, source-segment runs, and face graphs. Page boundaries are either algebraic from rows_per_page or compact complete-row spans derived from device work weights. The latter keeps skewed grouped workloads bounded without charging every row for the largest geometry in the batch.

left: object¶

right: object¶

row_count: int¶

rows_per_page: int¶

max_left_segments_per_row: int¶

max_right_segments_per_row: int¶

dispatch_mode: object¶

use_same_row_fast_path: bool | None = None¶

include_same_side_splits: bool = False¶

right_geometry_source_rows: vibespatial.cuda._runtime.DeviceArray | numpy.ndarray | None = None¶

right_segment_source_rows: vibespatial.cuda._runtime.DeviceArray | numpy.ndarray | None = None¶

right_segment_broadcast: object | None = None¶

allow_component_decomposition: bool = True¶

complete_row_spans: tuple[tuple[int, int], Ellipsis] | None = None¶

row_isolated: bool = True¶

property page_count: int¶

row_span(page_index: int) → tuple[int, int]¶