vibespatial.io.gpu_parse.indexing

Fused ingest + spatial index: build packed Hilbert R-tree during parsing.

Provides build_spatial_index which takes flat coordinate arrays and geometry offsets (the output of any GPU reader stage) and produces a packed Hilbert R-tree entirely on the device. No separate indexing pass is required.

ADR-0002: COARSE kernel class — bounding boxes stay fp64 because they are memory-bound (not compute-bound) and fp32 rounding shrinks bounds, causing false negatives in spatial filtering.

ADR-0033 tier classification:

• Tier 1 (NVRTC): compute_feature_bounds, compute_hilbert_codes

• Tier 2 (CuPy): R-tree node construction (element-wise gather/scatter)

• Tier 3a (CCCL): sort_pairs for Hilbert-order sorting

Attributes

cp

Classes

GpuSpatialIndex

Packed Hilbert R-tree built entirely on the GPU.

Functions

build_spatial_index(→ GpuSpatialIndex)	Build a packed Hilbert R-tree from coordinate arrays.
build_index_from_reader(→ GpuSpatialIndex)	Build spatial index from reader output — fused ingest step.

Module Contents

vibespatial.io.gpu_parse.indexing.cp = None

class vibespatial.io.gpu_parse.indexing.GpuSpatialIndex

Packed Hilbert R-tree built entirely on the GPU.

All arrays are CuPy device arrays. No host materialization occurs during construction.

Attributes

d_sorted_indicescp.ndarray (int32, n_features)

Feature indices in Hilbert curve order.

d_node_boundscp.ndarray (float64, (n_nodes, 4))

Per-node bounding boxes: min_x, min_y, max_x, max_y.

d_node_childrencp.ndarray (int32, (n_internal_nodes, node_capacity))

Child pointers per internal node. Leaf nodes are implicit (groups of node_capacity features in sorted order).

d_feature_boundscp.ndarray (float64, (n_features, 4))

Per-feature bounding boxes (in original feature order).

d_hilbert_codescp.ndarray (uint32, n_features)

Hilbert codes per feature (in original feature order).

n_featuresint

Number of features.

n_nodesint

Total number of nodes (leaves + internal).

n_leaf_nodesint

Number of leaf nodes.

node_capacityint

Maximum children per node (fan-out).

d_sorted_indices: object

d_node_bounds: object

d_node_children: object

d_feature_bounds: object

d_hilbert_codes: object

n_features: int

n_nodes: int

n_leaf_nodes: int

node_capacity: int

vibespatial.io.gpu_parse.indexing.build_spatial_index(d_x: cupy.ndarray, d_y: cupy.ndarray, geometry_offsets: cupy.ndarray, *, node_capacity: int = 16) → GpuSpatialIndex

Build a packed Hilbert R-tree from coordinate arrays.

All computation stays on the GPU. The returned GpuSpatialIndex contains device-resident arrays only — no host round-trips occur during construction.

Parameters

d_xcp.ndarray, float64

Flat X coordinate array on the device.

d_ycp.ndarray, float64

Flat Y coordinate array on the device.

geometry_offsetscp.ndarray, int32

Offset array of length n_features + 1 delimiting each feature’s coordinate span. feature[i] owns coordinates d_x[geometry_offsets[i]:geometry_offsets[i+1]].

node_capacityint

Fan-out per R-tree node (default 16).

Returns

GpuSpatialIndex

Packed Hilbert R-tree with all arrays on the device.

ADR-0002

COARSE kernel class. Bounds computed in fp64 (memory-bound; fp32 rounding shrinks bounds causing false negatives). Hilbert codes use integer arithmetic (uint32) — no precision concern.

vibespatial.io.gpu_parse.indexing.build_index_from_reader(d_x: cupy.ndarray, d_y: cupy.ndarray, geometry_offsets: cupy.ndarray, *, node_capacity: int = 16) → GpuSpatialIndex

Build spatial index from reader output — fused ingest step.

This is the intended entry point when building a spatial index as a side effect of file parsing. Functionally identical to build_spatial_index but documents the intended use as a composable stage in a reader pipeline.

Parameters

d_x, d_y, geometry_offsets

Same as build_spatial_index.

node_capacityint

Fan-out per R-tree node (default 16).

Returns

GpuSpatialIndex