vibespatial.geometry.owned¶

Attributes¶

`cp`
`NULL_TAG`
`FAMILY_TAGS`
`TAG_FAMILIES`

Classes¶

`DiagnosticKind`	Enum where members are also (and must be) strings
`BufferSharingMode`	Enum where members are also (and must be) strings
`DiagnosticEvent`
`FamilyGeometryBuffer`
`GeoArrowBufferView`
`MixedGeoArrowView`
`DeviceRegularGridRectMetadata`	Trusted regular rectangle-grid proof for device-resident polygon rows.
`DeviceFixedGeometrySizeMetadata`	Trusted fixed widths and variable-width per-row capacity bounds.
`DeviceFamilyGeometryBuffer`
`OwnedGeometryDeviceState`
`OwnedGeometryArray`	Columnar geometry storage with optional device-resident metadata.

Functions¶

`unique_tag_pairs`(→ list[tuple[int, int]])	Extract unique (left_tag, right_tag) pairs without Python-level iteration.
`seed_all_validity_cache`(→ None)	Seed the per-row validity cache with an all-valid mask.
`seed_homogeneous_host_metadata`(→ None)	Attach lightweight host routing metadata for a homogeneous owned output.
`device_family_coordinate_counts`(...)	Return device-resident coordinate spans for selected physical rows.
`ensure_device_geometry_size_bounds`(→ int)	Attach host-visible per-row size bounds derived from device offsets.
`build_updated_device_family_buffer`(...)	Rebuild a device family buffer after a span-preserving coordinate rewrite.
`build_updated_host_family_buffer`(→ FamilyGeometryBuffer)	Rebuild a host family buffer after a span-preserving coordinate rewrite.
`device_physicalize_owned_row_selections_exact`(...)	Gather several logical row selections through one exact-allocation packet.
`device_physicalize_owned_row_selection_capacity`(...)	Gather a masked rowset into a bounded physical device carrier.
`host_owned_axis_aligned_rectangle_batch`(→ bool \| None)	Classify a logical host-owned batch from canonical polygon buffers.
`normalize_buffer_sharing_mode`(→ BufferSharingMode)
`from_shapely_geometries`(→ OwnedGeometryArray)
`build_null_owned_array`(→ OwnedGeometryArray)	Build an all-null OwnedGeometryArray without materializing Shapely.
`from_wkb`(→ OwnedGeometryArray)
`from_geoarrow`(→ OwnedGeometryArray)
`concat_owned_scatter`(→ OwnedGeometryArray)	Scatter replacement rows into base at indices, returning a new array.
`concatenate_owned_arrays`(→ OwnedGeometryArray)	Concatenate owned geometry arrays without materializing geometry objects.
`device_concat_owned_scatter_many`(→ OwnedGeometryArray)	Scatter multiple device replacement partitions through one index map.
`device_scatter_owned_capacity_selection`(...)	Scatter replacement capacity through a dynamic device selection.
`device_scatter_owned_capacity_selections_many`(...)	Fuse multi-root capacity scatters through one exact physicalization.
`device_take_owned_family_capacity_selection`(...)	Build one homogeneous row-indirected family carrier at selection capacity.
`device_take_owned_capacity_selection`(→ OwnedGeometryArray)	Retain a dynamic selection as a row-indirected geometry capacity.
`device_select_owned_capacity_partitions`(...)	Select row-aligned capacity partitions through one device index map.
`device_physical_select_owned_capacity_partitions`(...)	Select row-aligned partitions into a bounded physical device carrier.
`device_mask_owned_capacity`(→ OwnedGeometryArray)	Create a null-padded row-capacity view over physical device buffers.
`device_concat_owned_scatter`(→ OwnedGeometryArray)	Scatter replacement rows into base without leaving the device.
`build_device_resident_owned`(→ OwnedGeometryArray)	Construct an OwnedGeometryArray from device buffers without touching host.
`build_empty_polygon_rows_device`(→ OwnedGeometryArray)	Build device empty-polygon rows with device-resident validity.
`device_valid_nonempty_mask`(owned)	Return logical-row valid/nonempty metadata without compact row discovery.
`forward_result_metadata`(...)	Forward metadata for a device result without forcing host copies.
`tile_single_row`(→ OwnedGeometryArray)	Create an N-row owned array from a 1-row owned array.
`materialize_broadcast`(→ OwnedGeometryArray)	Physically replicate coordinate buffers in a tiled owned array.

Module Contents¶

vibespatial.geometry.owned.cp = None¶

vibespatial.geometry.owned.NULL_TAG = -1¶

vibespatial.geometry.owned.FAMILY_TAGS: dict[vibespatial.geometry.buffers.GeometryFamily, int]¶

vibespatial.geometry.owned.TAG_FAMILIES¶

vibespatial.geometry.owned.unique_tag_pairs(left_tags: numpy.ndarray, right_tags: numpy.ndarray) → list[tuple[int, int]]¶

Extract unique (left_tag, right_tag) pairs without Python-level iteration.

Works with both numpy and CuPy arrays. Packs two int8 tags into one int16 and calls the array library’s unique, then unpacks the small result (at most 36 pairs for 6 geometry families) on the host.

This replaces the set(zip(left.tolist(), right.tolist())) anti-pattern which forces a full-array D->H transfer and O(n) Python iteration.

Precondition: tag values must be non-negative and fit in int8 (0..127). Callers must filter null rows (NULL_TAG = -1) before calling.

vibespatial.geometry.owned.seed_all_validity_cache(owned: OwnedGeometryArray | None) → None¶

Seed the per-row validity cache with an all-valid mask.

Exact overlay/clip results and successful post-repair outputs are already normalized geometry buffers. Marking them valid avoids re-running full OGC validity scans when those public results feed immediately into another polygon operation.

vibespatial.geometry.owned.seed_homogeneous_host_metadata(owned: OwnedGeometryArray | None, family: vibespatial.geometry.buffers.GeometryFamily) → None¶

Attach lightweight host routing metadata for a homogeneous owned output.

GPU builders often know that every output row is valid and belongs to one family. In that case validity/tags/family offsets can be synthesized on host without materializing any coordinate payload or copying metadata back from device state.

class vibespatial.geometry.owned.DiagnosticKind¶

Enum where members are also (and must be) strings

CREATED = 'created'¶

TRANSFER = 'transfer'¶

MATERIALIZATION = 'materialization'¶

RUNTIME = 'runtime'¶

CACHE = 'cache'¶

FALLBACK = 'fallback'¶

class vibespatial.geometry.owned.BufferSharingMode¶

Enum where members are also (and must be) strings

COPY = 'copy'¶

SHARE = 'share'¶

AUTO = 'auto'¶

class vibespatial.geometry.owned.DiagnosticEvent¶

kind: DiagnosticKind¶

detail: str¶

residency: vibespatial.runtime.residency.Residency¶

visible_to_user: bool = False¶

elapsed_seconds: float = 0.0¶

bytes_transferred: int = 0¶

class vibespatial.geometry.owned.FamilyGeometryBuffer¶

family: vibespatial.geometry.buffers.GeometryFamily¶

schema: vibespatial.geometry.buffers.GeometryBufferSchema¶

row_count: int¶

x: numpy.ndarray¶

y: numpy.ndarray¶

geometry_offsets: numpy.ndarray¶

empty_mask: numpy.ndarray¶

part_offsets: numpy.ndarray | None = None¶

ring_offsets: numpy.ndarray | None = None¶

bounds: numpy.ndarray | None = None¶

host_materialized: bool = True¶

class vibespatial.geometry.owned.GeoArrowBufferView¶

family: vibespatial.geometry.buffers.GeometryFamily¶

x: numpy.ndarray¶

y: numpy.ndarray¶

geometry_offsets: numpy.ndarray¶

empty_mask: numpy.ndarray¶

part_offsets: numpy.ndarray | None = None¶

ring_offsets: numpy.ndarray | None = None¶

bounds: numpy.ndarray | None = None¶

shares_memory: bool = False¶

class vibespatial.geometry.owned.MixedGeoArrowView¶

validity: numpy.ndarray¶

tags: numpy.ndarray¶

family_row_offsets: numpy.ndarray¶

families: dict[vibespatial.geometry.buffers.GeometryFamily, GeoArrowBufferView]¶

shares_memory: bool = False¶

class vibespatial.geometry.owned.DeviceRegularGridRectMetadata¶

Trusted regular rectangle-grid proof for device-resident polygon rows.

origin_x: float¶

origin_y: float¶

cell_width: float¶

cell_height: float¶

cols: int¶

rows: int¶

size: int¶

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

class vibespatial.geometry.owned.DeviceFixedGeometrySizeMetadata¶

Trusted fixed widths and variable-width per-row capacity bounds.

first_level_count_per_row: int | None = None¶

second_level_count_per_row: int | None = None¶

coord_count_per_row: int | None = None¶

max_first_level_count_per_row: int | None = None¶

max_second_level_count_per_row: int | None = None¶

max_coord_count_per_row: int | None = None¶

class vibespatial.geometry.owned.DeviceFamilyGeometryBuffer¶

family: vibespatial.geometry.buffers.GeometryFamily¶

x: vibespatial.cuda._runtime.DeviceArray¶

y: vibespatial.cuda._runtime.DeviceArray¶

geometry_offsets: vibespatial.cuda._runtime.DeviceArray¶

empty_mask: vibespatial.cuda._runtime.DeviceArray¶

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

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

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

dense_single_ring_width: int | None = None¶

axis_aligned_rectangles: bool = False¶

regular_grid_rect: DeviceRegularGridRectMetadata | None = None¶

fixed_size: DeviceFixedGeometrySizeMetadata | None = None¶

vibespatial.geometry.owned.device_family_coordinate_counts(buffer: DeviceFamilyGeometryBuffer, source_rows: vibespatial.cuda._runtime.DeviceArray | None = None) → vibespatial.cuda._runtime.DeviceArray¶: Return device-resident coordinate spans for selected physical rows.

vibespatial.geometry.owned.ensure_device_geometry_size_bounds(owned: OwnedGeometryArray, *, reason: str) → int¶

Attach host-visible per-row size bounds derived from device offsets.

Variable-width native inputs can arrive without fixed-size metadata even though their nested offsets already prove tight allocation bounds. Reduce every missing family proof on device and export one small planning packet; geometry coordinates and row metadata remain resident.

Returns the maximum coordinate span of any segment-producing source row. A coordinate span is a conservative segment bound for lineal/polygonal families and can therefore size row-isolated topology pages safely.

vibespatial.geometry.owned.build_updated_device_family_buffer(family: vibespatial.geometry.buffers.GeometryFamily, device_buf: DeviceFamilyGeometryBuffer, d_x_out: vibespatial.cuda._runtime.DeviceArray, d_y_out: vibespatial.cuda._runtime.DeviceArray, d_new_offsets: vibespatial.cuda._runtime.DeviceArray) → DeviceFamilyGeometryBuffer¶: Rebuild a device family buffer after a span-preserving coordinate rewrite.

vibespatial.geometry.owned.build_updated_host_family_buffer(family: vibespatial.geometry.buffers.GeometryFamily, host_buf: FamilyGeometryBuffer, x_out: numpy.ndarray, y_out: numpy.ndarray, new_offsets: numpy.ndarray) → FamilyGeometryBuffer¶: Rebuild a host family buffer after a span-preserving coordinate rewrite.

class vibespatial.geometry.owned.OwnedGeometryDeviceState¶

validity: vibespatial.cuda._runtime.DeviceArray¶

tags: vibespatial.cuda._runtime.DeviceArray¶

family_row_offsets: vibespatial.cuda._runtime.DeviceArray¶

families: dict[vibespatial.geometry.buffers.GeometryFamily, DeviceFamilyGeometryBuffer]¶

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

trusted_all_valid: bool | None = None¶

trusted_all_ogc_valid: bool | None = None¶

trusted_homogeneous_family: vibespatial.geometry.buffers.GeometryFamily | None = None¶

trusted_all_non_empty: bool | None = None¶

trusted_nonempty_polygonal_positive_area: bool | None = None¶

trusted_polygonal_only: bool | None = None¶

trusted_unique_family_rows: bool | None = None¶

trusted_family_domain: tuple[vibespatial.geometry.buffers.GeometryFamily, Ellipsis] | None = None¶

point_location_indexes: dict[vibespatial.geometry.buffers.GeometryFamily, Any]¶

polygon_certificates: dict[tuple[str, vibespatial.geometry.buffers.GeometryFamily, int], Any]¶

class vibespatial.geometry.owned.OwnedGeometryArray(validity: numpy.ndarray | None, tags: numpy.ndarray | None, family_row_offsets: numpy.ndarray | None, families: dict[vibespatial.geometry.buffers.GeometryFamily, FamilyGeometryBuffer], residency: vibespatial.runtime.residency.Residency = Residency.HOST, diagnostics: list[DiagnosticEvent] | None = None, runtime_history: list[vibespatial.runtime.RuntimeSelection] | None = None, geoarrow_backed: bool = False, shares_geoarrow_memory: bool = False, device_adopted: bool = False, device_state: OwnedGeometryDeviceState | None = None, _row_count: int | None = None)¶

Columnar geometry storage with optional device-resident metadata.

The three routing metadata arrays – validity, tags, and family_row_offsets – are exposed as properties. When the array is device-resident, the host numpy copies may be None internally; accessing any property lazily transfers from GPU to CPU, preserving full backward compatibility for host consumers while allowing GPU-only pipelines to avoid the D->H transfer entirely.

families¶

residency¶

diagnostics: list[DiagnosticEvent] = None¶

runtime_history: list[vibespatial.runtime.RuntimeSelection] = None¶

geoarrow_backed = False¶

shares_geoarrow_memory = False¶

device_adopted = False¶

device_state = None¶

property validity: numpy.ndarray¶

property tags: numpy.ndarray¶

property family_row_offsets: numpy.ndarray¶

property row_count: int¶

property is_indexed_view: bool¶: True when this array is a virtual indexed view over a compact base.

detach_expanded_device_view() → OwnedGeometryArray¶

Promote an expanded device view to a standalone shared-buffer carrier.

Device indexed views with an expanded device_state already own their logical routing metadata; only family coordinate buffers are shared with the source. Clearing the source row map is therefore a zero-copy ownership transition. It is useful at bounded chunk boundaries where retaining the source scatter root would otherwise retain inactive workspace lanes until terminal assembly.

Deferred-metadata views cannot detach because their row map is still required to derive logical routing metadata.

physicalize_device_rows(*, allow_capacity_allocation: bool = False) → OwnedGeometryArray¶

Return a contiguous device carrier for an indexed row view.

This is an explicit physical-layout transition for kernels that cannot consume row indirection. It never exports row metadata and leaves the source view intact so callers cannot accidentally erase shared-carrier provenance while preparing a constructive input.

family_has_rows(family: vibespatial.geometry.buffers.GeometryFamily) → bool¶

Check whether family has at least one geometry row to process.

Reads from whichever side is authoritative: device_state when populated, host FamilyGeometryBuffer otherwise. This avoids the bug where host stubs with host_materialized=False report empty offsets even when device buffers have real data.

move_to(target: vibespatial.runtime.residency.Residency | str, *, trigger: vibespatial.runtime.residency.TransferTrigger | str, reason: str | None = None) → OwnedGeometryArray¶

record_runtime_selection(selection: vibespatial.runtime.RuntimeSelection) → None¶

cache_bounds(bounds: numpy.ndarray) → None¶

cache_device_bounds(family: vibespatial.geometry.buffers.GeometryFamily, bounds: vibespatial.cuda._runtime.DeviceArray) → None¶

classmethod concat(arrays: list[OwnedGeometryArray]) → OwnedGeometryArray¶

Concatenate multiple OwnedGeometryArrays at the buffer level.

When ALL inputs are device-resident (residency == DEVICE) and have device state populated, concatenation is performed entirely on GPU using CuPy – no D->H transfer occurs. The result is a device-resident OGA with lazy host stubs.

When ANY input is host-resident (or lacks device state), falls back to the existing host-side concatenation path.

diagnostics_report() → dict[str, Any]¶

take(indices: numpy.ndarray) → OwnedGeometryArray¶

Return a new OwnedGeometryArray containing only the rows at indices.

Operates entirely at the buffer level – no Shapely round-trip. When the array is DEVICE-resident or indices are already on device (CuPy / __cuda_array_interface__), dispatches to device_take() to keep all gathering on GPU. Otherwise returns a HOST-resident array.

When the indices have high repetition (many output rows mapping to few unique source rows), returns a virtual indexed view that stores only the unique rows and an index map, avoiding the physical coordinate copy. This is transparent to consumers: kernel dispatch triggers _resolve(), and to_shapely() expands via cheap Python object references.

Memory pressure is handled by the ADR-0040 tiered allocator: Tier B (default) retries with gc.collect on OOM; Tier C (opt-in) uses CUDA managed memory for datasets exceeding VRAM.

device_take(indices, *, host_indices_for_sizing: numpy.ndarray | None = None, allow_capacity_allocation: bool = False, assume_unique_indices: bool = False) → OwnedGeometryArray¶

Device-side take — all gathering stays on GPU.

Accepts numpy or CuPy indices/mask. Returns a DEVICE-resident OwnedGeometryArray with host buffers marked host_materialized=False. The host side is lazily populated by _ensure_host_state() on demand.

When indices have high repetition, returns a virtual indexed view instead of performing a full device gather. See take() for the design rationale.

device_take_capacity(indices, active_mask) → OwnedGeometryArray¶

Take capacity rows and mark inactive device lanes null.

The logical cardinality remains in the calling native selection carrier. Variable-width geometry keeps its indexed row carrier so a sparse capacity selection cannot multiply the physical coordinate allocation; consumers that require contiguous storage must request an explicit physicalization from that carrier.

to_shapely() → list[object | None]¶

to_wkb(*, hex: bool = False) → list[bytes | str | None]¶

to_geoarrow(*, sharing: BufferSharingMode | str = BufferSharingMode.COPY) → MixedGeoArrowView¶

vibespatial.geometry.owned.device_physicalize_owned_row_selections_exact(selections: list[tuple[OwnedGeometryArray, vibespatial.cuda._runtime.DeviceArray]], *, reason: str, compact_concrete_prefix: bool = False) → list[OwnedGeometryArray | None]¶

Gather several logical row selections through one exact-allocation packet.

This is the physical-layout boundary for multi-root native compositions. Coordinates and nested offsets remain on device; only aggregate allocation totals cross once so each selected span is copied exactly once. When compact_concrete_prefix is true, every active lane must be concrete and active lanes must form a prefix. The result then uses that prefix’s exact logical row count instead of retaining source capacity.

vibespatial.geometry.owned.device_physicalize_owned_row_selection_capacity(owned: OwnedGeometryArray, active_mask: vibespatial.cuda._runtime.DeviceArray) → OwnedGeometryArray¶

Gather a masked rowset into a bounded physical device carrier.

The row capacity and family width metadata size every allocation on the host. Dynamic activity remains a device mask, so this transition does not export selected counts or nested offset totals. The identity row map is injective by construction and each active coordinate span is copied once.

vibespatial.geometry.owned.host_owned_axis_aligned_rectangle_batch(owned: OwnedGeometryArray) → bool | None¶

Classify a logical host-owned batch from canonical polygon buffers.

None means the host carrier is not materialized enough to answer without a device transfer. False is an authoritative structural rejection; True proves every logical row is a valid rectangle polygon.

vibespatial.geometry.owned.normalize_buffer_sharing_mode(mode: BufferSharingMode | str) → BufferSharingMode¶

vibespatial.geometry.owned.from_shapely_geometries(geometries: list[object | None] | tuple[object | None, Ellipsis], *, residency: vibespatial.runtime.residency.Residency = Residency.HOST) → OwnedGeometryArray¶

vibespatial.geometry.owned.build_null_owned_array(row_count: int, *, residency: vibespatial.runtime.residency.Residency = Residency.HOST) → OwnedGeometryArray¶: Build an all-null OwnedGeometryArray without materializing Shapely.

vibespatial.geometry.owned.from_wkb(values: list[bytes | str | None] | tuple[bytes | str | None, Ellipsis], *, on_invalid: str = 'raise', residency: vibespatial.runtime.residency.Residency = Residency.HOST) → OwnedGeometryArray¶

vibespatial.geometry.owned.from_geoarrow(view: MixedGeoArrowView, *, residency: vibespatial.runtime.residency.Residency = Residency.HOST, sharing: BufferSharingMode | str = BufferSharingMode.COPY) → OwnedGeometryArray¶

vibespatial.geometry.owned.concat_owned_scatter(base: OwnedGeometryArray, replacement: OwnedGeometryArray, indices: numpy.ndarray) → OwnedGeometryArray¶

Scatter replacement rows into base at indices, returning a new array.

Returns a new OwnedGeometryArray with the same row count as base where: - rows at indices come from replacement (in order) - all other rows come from base

len(indices) must equal replacement.row_count.

Operates entirely at the buffer level — no Shapely materialisation. When both inputs are device-resident, dispatches to device_concat_owned_scatter() so the result stays on GPU.

vibespatial.geometry.owned.concatenate_owned_arrays(arrays: list[OwnedGeometryArray]) → OwnedGeometryArray¶: Concatenate owned geometry arrays without materializing geometry objects.

vibespatial.geometry.owned.device_concat_owned_scatter_many(base: OwnedGeometryArray, replacements: list[tuple[OwnedGeometryArray, numpy.ndarray | vibespatial.cuda._runtime.DeviceArray]]) → OwnedGeometryArray¶

Scatter multiple device replacement partitions through one index map.

Physical shape: row-indirected native assembly. This is the fused variant of repeated device_concat_owned_scatter calls for partitioned constructive outputs. The base and all replacement buffers are concatenated once, then one device row map selects the winning row for each public output position.

vibespatial.geometry.owned.device_scatter_owned_capacity_selection(base: OwnedGeometryArray, replacement: OwnedGeometryArray, selection, *, active_mask: vibespatial.cuda._runtime.DeviceArray | None = None) → OwnedGeometryArray¶

Scatter replacement capacity through a dynamic device selection.

replacement has one row per selection-capacity lane. Active lanes map to source rows through selection.positions; inactive lanes map to scratch destinations beyond the public output. The original and replacement carriers are concatenated once, and the result remains row-indirected with no logical-count read or variable-width geometry compaction.

vibespatial.geometry.owned.device_scatter_owned_capacity_selections_many(base: OwnedGeometryArray, replacements: list[tuple[OwnedGeometryArray, Any, vibespatial.cuda._runtime.DeviceArray | None]]) → OwnedGeometryArray¶

Fuse multi-root capacity scatters through one exact physicalization.

A single-root OwnedGeometryArray cannot retain row indirection into several unrelated geometry buffers. This is the explicit physical-layout boundary for that shape: all active logical rows are sized by one sparse device packet, copied once, concatenated once, and selected by one row map.

vibespatial.geometry.owned.device_take_owned_family_capacity_selection(owned: OwnedGeometryArray, selection, family: vibespatial.geometry.buffers.GeometryFamily) → OwnedGeometryArray¶

Build one homogeneous row-indirected family carrier at selection capacity.

The selected prefix gathers only row metadata. Coordinates and structural offsets remain in the source family buffer and are addressed through the gathered family-row offsets. Rejected tail lanes are null. This is the native layout for family kernels: logical row capacity over shared physical family storage, with no variable-width copy or cardinality fence.

vibespatial.geometry.owned.device_take_owned_capacity_selection(owned: OwnedGeometryArray, selection) → OwnedGeometryArray¶

Retain a dynamic selection as a row-indirected geometry capacity.

NativeDeviceSelection carries a stable full partition, not just the selected prefix. Addressing that partition keeps every source row unique in physical storage while the separate activity mask nulls the inactive tail. This avoids copying the first selected variable-width geometry into every inactive lane, which can multiply nested allocation capacity.

vibespatial.geometry.owned.device_select_owned_capacity_partitions(base: OwnedGeometryArray, replacements: list[tuple[OwnedGeometryArray, vibespatial.cuda._runtime.DeviceArray]]) → OwnedGeometryArray¶

Select row-aligned capacity partitions through one device index map.

Every replacement has the public row capacity of base. Its mask marks lanes that own the logical output. Variable-width buffers are concatenated once and remain row-indirected; no partition cardinality is materialized. Later replacements win if masks overlap.

vibespatial.geometry.owned.device_physical_select_owned_capacity_partitions(base: OwnedGeometryArray, replacements: list[tuple[OwnedGeometryArray, vibespatial.cuda._runtime.DeviceArray]]) → OwnedGeometryArray¶

Select row-aligned partitions into a bounded physical device carrier.

Iterative constructive reductions must not retain every prior selection source in an indexed-view ancestry graph. This explicit physical-layout transition performs the row selection without exporting cardinality, then gathers each selected variable-width row once. The selection map is injective across concatenated sources, so nested allocation is bounded by the source carriers rather than multiplied by output-row capacity.

vibespatial.geometry.owned.device_mask_owned_capacity(owned: OwnedGeometryArray, active_mask: vibespatial.cuda._runtime.DeviceArray, *, preserve_row_bounds: bool = True) → OwnedGeometryArray¶

Create a null-padded row-capacity view over physical device buffers.

The geometry buffers are shared. Only row-aligned validity, tags, family row offsets, and cached bounds are rewritten, so complementary constructive partitions can consume the same physical rows without a sparse take or a variable-width coordinate copy.

vibespatial.geometry.owned.device_concat_owned_scatter(base: OwnedGeometryArray, replacement: OwnedGeometryArray, indices: numpy.ndarray | vibespatial.cuda._runtime.DeviceArray) → OwnedGeometryArray¶: Scatter replacement rows into base without leaving the device.

vibespatial.geometry.owned.build_device_resident_owned(*, device_families: dict[vibespatial.geometry.buffers.GeometryFamily, DeviceFamilyGeometryBuffer], row_count: int, tags: numpy.ndarray | vibespatial.cuda._runtime.DeviceArray, validity: numpy.ndarray | vibespatial.cuda._runtime.DeviceArray, family_row_offsets: numpy.ndarray | vibespatial.cuda._runtime.DeviceArray, execution_mode: str | None = None) → OwnedGeometryArray¶

Construct an OwnedGeometryArray from device buffers without touching host.

This is the canonical factory for producing device-resident results from GPU kernels. Host-side FamilyGeometryBuffers are created with empty coordinate stubs (host_materialized=False); actual data lives only in the device_state. Lazy _ensure_host_state will copy on demand if the caller ever needs Shapely objects.

Parameters¶

device_families: Per-family device buffers produced by a GPU kernel.
row_count: Total number of rows (geometries) in the output.
tags: int8 array of family tags, length row_count.
validity: bool array, length row_count.
family_row_offsets: int32 array mapping global row index to family-local row index.
execution_mode: Optional execution mode marker. When set to "gpu", host numpy metadata arrays are rejected so GPU-path callers cannot silently re-upload metadata through this factory.

vibespatial.geometry.owned.build_empty_polygon_rows_device(row_count: int, *, validity: vibespatial.cuda._runtime.DeviceArray | None = None) → OwnedGeometryArray¶: Build device empty-polygon rows with device-resident validity.

vibespatial.geometry.owned.device_valid_nonempty_mask(owned: OwnedGeometryArray)¶: Return logical-row valid/nonempty metadata without compact row discovery.

vibespatial.geometry.owned.forward_result_metadata(owned: OwnedGeometryArray) → tuple[numpy.ndarray | vibespatial.cuda._runtime.DeviceArray, numpy.ndarray | vibespatial.cuda._runtime.DeviceArray, numpy.ndarray | vibespatial.cuda._runtime.DeviceArray]¶

Forward metadata for a device result without forcing host copies.

When the source already has device metadata, reuse those arrays directly so downstream device-resident builders do not pay a D->H->D round-trip. Otherwise, preserve the historical host-copy behavior for host-only inputs.

vibespatial.geometry.owned.tile_single_row(owned: OwnedGeometryArray, n: int) → OwnedGeometryArray¶

Create an N-row owned array from a 1-row owned array.

The coordinate buffers (x, y) and offset arrays inside each FamilyGeometryBuffer are shared with the original – only the three routing metadata arrays (validity, tags, family_row_offsets) are replicated. This makes the operation O(N) in tiny int8/int32/bool metadata, not O(N * vertex_count) in fp64 coordinates, eliminating the host-side materialization bottleneck for scalar broadcast (nsf.3/nsf.4).

Parameters¶

owned: Must have row_count == 1.
n: Desired number of output rows.

Returns¶

OwnedGeometryArray: An n-row array where every row references the same geometry as the single input row. The family buffers have row_count == 1 and every row’s family_row_offsets entry is 0.

vibespatial.geometry.owned.materialize_broadcast(tiled: OwnedGeometryArray) → OwnedGeometryArray¶

Physically replicate coordinate buffers in a tiled owned array.

tile_single_row() creates an N-row metadata facade that shares the 1-row coordinate buffers. GPU kernels that index into family buffers by global row index require family_buf.row_count == n. This function converts the metadata-only tile into a fully- materialized array where each family buffer has n physical rows with replicated coordinate data.

The operation is O(N * vertices_per_geometry) in coordinate copies but avoids per-element Python loops and the Shapely round-trip that would otherwise be required. It is only called for the GPU path of broadcast-right constructive operations.

Parameters¶

tiled: An OwnedGeometryArray produced by tile_single_row() (N-row metadata, 1-row family buffers with all family_row_offsets == 0).

Returns¶

OwnedGeometryArray: Same metadata but with physically replicated family buffers where family_buf.row_count == tiled.row_count.