vibespatial.io.wkt_gpu

GPU WKT reader – structural analysis, coordinate extraction, and assembly.

GPU-accelerated WKT parser. Given a device-resident byte array containing one or more WKT geometries (one per line), this module performs:

  1. Fixed-capacity row discovery – detect newline-delimited geometry starts without a data-dependent selection.

  2. Geometry type classification – a custom NVRTC kernel scans the start of each geometry string and emits a family tag (POINT=0, LINESTRING=1, POLYGON=2, MULTIPOINT=3, MULTILINESTRING=4, MULTIPOLYGON=5) plus an EMPTY flag. Handles case-insensitive matching and EWKT SRID=NNNN; prefixes.

  3. Capacity count/validation – one row-parallel kernel validates numeric grammar and topology while counting family output sizes.

  4. Exact numeric conversion – fixed-capacity token spans feed an NVRTC binary64 parser with an exact common path and midpoint refinement.

  5. Planning boundary – one compact D2H packet preserves synchronous error semantics and provides exact family allocation totals.

  6. Direct family scatter – a second kernel writes parsed coordinates into exact owned buffers without data-dependent CuPy selection.

Geometry text and coordinates remain device-resident. The only successful parse transfer is the explicit semantic-validation/allocation packet.

Tier classification (ADR-0033):

  • Row discovery: Tier 2 (fixed-shape CuPy scan + Tier 1 scatter)

  • Type classification: Tier 1 (custom NVRTC – text-specific prefix matching)

  • Count/validation: Tier 1 (custom NVRTC – row-capacity parse)

  • Numeric conversion: Tier 1 exact parse and rounding refinement

  • Coordinate/topology scatter: Tier 1 (custom NVRTC – family-specialized)

  • Offset building: Tier 2 (CuPy cumsum) / CCCL exclusive_sum

  • Assembly: follows geojson_gpu.py patterns

Precision (ADR-0002):

Structural and counting kernels are integer-only byte classification. No floating-point coordinate computation occurs in those kernels, so no PrecisionPlan is needed (same rationale as gpu_parse/structural.py). Coordinate parsing always produces fp64 storage per ADR-0002.

Attributes

cp

KERNEL_PARAM_I64

Classes

WktStructuralResult

Result of WKT structural analysis.

Functions

wkt_structural_analysis(→ WktStructuralResult)

Perform structural analysis and geometry type detection on WKT input.

read_wkt_gpu(...)

Parse WKT bytes on GPU and return device-resident geometry.

Module Contents

vibespatial.io.wkt_gpu.cp = None
vibespatial.io.wkt_gpu.KERNEL_PARAM_I64
class vibespatial.io.wkt_gpu.WktStructuralResult

Result of WKT structural analysis.

All arrays are device-resident CuPy arrays except n_geometries which is a Python int.

Attributes

d_depthcp.ndarray

Per-byte parenthesis depth, int32, shape (n_bytes,).

d_geom_startscp.ndarray

Start byte offset of each geometry, int64, shape (n_geometries,).

d_family_tagscp.ndarray

Geometry family tag per geometry, int8, shape (n_geometries,). Values: 0=POINT, 1=LINESTRING, 2=POLYGON, 3=MULTIPOINT, 4=MULTILINESTRING, 5=MULTIPOLYGON, -2=unknown/unsupported.

d_empty_flagscp.ndarray

Per-geometry EMPTY flag, uint8, shape (n_geometries,). 1 if the geometry uses the EMPTY keyword, 0 otherwise.

n_geometriesint

Number of geometries detected.

d_depth: cupy.ndarray
d_geom_starts: cupy.ndarray
d_family_tags: cupy.ndarray
d_empty_flags: cupy.ndarray
n_geometries: int
vibespatial.io.wkt_gpu.wkt_structural_analysis(d_bytes: cupy.ndarray) → WktStructuralResult

Perform structural analysis and geometry type detection on WKT input.

Given a device-resident byte array containing one or more WKT geometry strings separated by newlines, this function:

  1. Detects line boundaries (newline positions) to delimit geometries.

  2. Computes per-byte parenthesis depth using bracket_depth.

  3. Classifies each geometry by type keyword and detects EMPTY.

The input may contain:

  • Standard WKT: POINT(1 2)

  • EWKT with SRID prefix: SRID=4326;POINT(1 2)

  • Mixed case: Point(1 2), LINESTRING(...)

  • 2D geometry only; Z/M/ZM suffixes are classified as unsupported

  • Empty geometries: POINT EMPTY

Parameters

d_bytescp.ndarray

Device-resident uint8 array of WKT text bytes, shape (n,). Multiple geometries are separated by newline characters (\n, 0x0A). Trailing newlines are handled gracefully.

Returns

WktStructuralResult

Dataclass containing all structural analysis outputs on device.

Notes

WKT has no string quoting, so bracket_depth receives an all-zeros quote-parity array. This causes the depth kernel to treat every parenthesis as structural.

The parenthesis depth array uses the same convention as the GeoJSON bracket depth:

  • Depth 0: outside all geometry parentheses

  • Depth 1: inside the outermost (...)

  • Depth 2+: nested rings, coordinate groups, etc.

Examples

>>> import cupy as cp
>>> wkt = b"POINT(1 2)\nLINESTRING(0 0, 1 1)\nPOLYGON EMPTY"
>>> d_bytes = cp.frombuffer(wkt, dtype=cp.uint8)
>>> result = wkt_structural_analysis(d_bytes)
>>> result.n_geometries
3
>>> result.d_family_tags.get()  # array([0, 1, 2], dtype=int8)
>>> result.d_empty_flags.get()  # array([0, 0, 1], dtype=uint8)
vibespatial.io.wkt_gpu.read_wkt_gpu(d_bytes: cupy.ndarray, *, row_count_hint: int | None = None, on_invalid: Literal['raise', 'warn', 'ignore'] = 'raise', input_validity: cupy.ndarray | None = None) → vibespatial.geometry.owned.OwnedGeometryArray

Parse WKT bytes on GPU and return device-resident geometry.

Given a device-resident byte array containing one or more WKT geometry strings separated by newlines, this function performs full GPU-accelerated parsing: structural analysis, coordinate extraction, and assembly into an OwnedGeometryArray.

Supported geometry types:

  • POINT, LINESTRING, POLYGON (full support)

  • MULTIPOINT, MULTILINESTRING, MULTIPOLYGON

  • EMPTY variants of all types

Parameters

d_bytescp.ndarray

Device-resident uint8 array of WKT text bytes, shape (n,). Multiple geometries are separated by newline characters (\n, 0x0A).

row_count_hintint, optional

Host-known number of input rows. Public ingress should provide this structural metadata so row scratch uses exact capacity. Raw device byte callers may omit it; byte count then provides a safe capacity.

Returns

OwnedGeometryArray

Device-resident geometry array. Coordinates are always fp64. Structural metadata (offsets, validity) is materialized on both host and device per the standard _build_device_*_owned pattern.

Raises

ValueError

If the input contains unsupported geometry types or dimensional coordinates (Z, M, or ZM), or cannot be parsed.

Notes

Precision (ADR-0002):

All coordinates are parsed and stored as fp64. The structural analysis and counting kernels are integer-only byte classification – no PrecisionPlan is needed for those stages.

Tier classification (ADR-0033):

Uses Tier 1 (custom NVRTC) for geometry-specific scanning and exact binary64 refinement, and Tier 2 (CuPy) for fixed-shape element-wise operations.

Examples

>>> import cupy as cp
>>> wkt = b"POINT(1 2)\nLINESTRING(0 0, 1 1, 2 0)"
>>> d_bytes = cp.frombuffer(wkt, dtype=cp.uint8)
>>> owned = read_wkt_gpu(d_bytes)
>>> owned.row_count
2