cuSpatial 25.04: legacy GPU spatial workflow checks

Legacy cuSpatial workflow. The final cuSpatial release was 25.04, and NVIDIA stopped publishing its packages and including it in RAPIDS containers and the metapackage from 25.06. See the support notice. This page outlines checks for an existing pinned environment; it is not a current RAPIDS installation recipe.

What we’ll cover

• Recording a compatible legacy environment
• Checking cuDF/cuSpatial versions before using an API
• Two core patterns: point‑in‑polygon and point‑in‑polygon at scale (with spatial filtering)
• A reproducible correctness and timing checklist
• VRAM, I/O, and projection pitfalls

Prepare and validate your GPU workload

Check the available configuration and software compatibility before launching. Measure results against a reference and keep an independent backup of your inputs and outputs.

Try Compute now

1) Choose your image

For an existing cuSpatial workflow, preserve a known working environment and record its exact dependencies. Do not assume that a current RAPIDS image includes cuSpatial.

A) Reproduce an existing image

• Record the actual registry path, tag and digest of a tested image. A placeholder such as 24.xx is not an installable version or evidence of compatibility.
• Env vars:
  • NVIDIA_VISIBLE_DEVICES=all
  • NVIDIA_DRIVER_CAPABILITIES=compute,utility
• CMD: keep your startup script or an interactive shell.

B) Reproduce an explicit dependency lock

Restore the environment from a reviewed lock file for the selected cuSpatial release. Record Python, cuDF, RMM, CUDA and driver requirements. Confirm imports and a small correctness fixture before loading real data; a floating install command is not a reproducibility test.

These are reproduction options, not verified installation instructions. Package availability, compatibility and maintenance status must be assessed for the retained environment.

2) Data formats that play well

• GeoParquet can preserve geometry and CRS metadata. Read it with a geometry-aware reader; a generic Parquet table is not automatically a cuSpatial geometry object.
• Shapefile works, but prefer converting to GeoParquet once.
• Use the same coordinate reference system and axis order for points and polygons. For distance or area calculations, choose a suitable projected CRS rather than treating longitude/latitude as metric coordinates.

3) Point‑in‑polygon (PIP): the basic pattern

Start with a small fixture whose expected results are known: interior, exterior, boundary and hole cases. The versioned API must match the installed environment.

The 25.04 reference takes point and polygon GeoSeries in point_in_polygon. Do not reuse the older six-array call without checking the installed version. Build valid geometries, run the fixture and compare identifiers and results with a CPU reference before scaling.

Notes

• Define the output you need: point membership in any polygon, or every point–polygon pair. Reducing matches to a single boolean per point discards polygon identity and overlapping matches.
• Use coordinate types accepted by the selected API and validate precision on your data, especially near boundaries.

4) PIP at scale: filter then test

Use spatial indexing to build relevant point–polygon candidates. A single envelope around all polygons only excludes points outside that overall extent; it is not a per-polygon spatial join.

For a version-matched indexed workflow, preserve original point and polygon identifiers through sorting, candidate generation and exact testing. Check the indexed output against the small unindexed reference. Do not infer polygon matches from a global bounding box or lose identifiers when reducing a boolean matrix.

Measure candidate reduction and end-to-end time. An index can add overhead, and a dense point-by-polygon result can exceed memory even if the input coordinates fit.

5) Reading real data (GeoParquet)

Use a geometry-aware GeoParquet reader, inspect its CRS and geometries, then convert using the selected cuSpatial version’s documented path. A custom table of exploded rings is a separate schema: define its offsets, multipart structure and identifiers explicitly.

After any format conversion, compare feature counts, identifiers, geometry validity and CRS. Keep the source data until the converted dataset passes those checks.

6) Partitioning larger workloads

Treat a distributed implementation as a separate engineering task. Check that the geometry functions and data conversions work on each worker.

• Partition points across workers/GPUs.
• Distribute polygons only when their memory footprint and the join strategy permit it; otherwise design spatial partitions.
• Preserve identifiers, handle partition boundaries and reconcile missing or duplicate matches.

Wrapping a cuDF table in Dask does not by itself supply a correct distributed spatial join. Validate the combined result against a reference before measuring throughput.

7) Performance measurement checklist

Use the same inputs, output definition and correctness checks for each comparison.

Record input counts, geometry complexity, CRS, coordinate precision, software lock, hardware and expected results. Measure loading, conversion, indexing, exact testing and output separately, with GPU synchronization where required for timing.

Compute cost per million points:

For a nonzero count of successfully processed points: cost per million = total measured run cost × 1,000,000 / point count. State the polygon workload and output definition so comparisons use the same task.

8) VRAM & performance tips

• VRAM: keep an eye on nvidia-smi. If close to full, chunk the point table.
• CRS: verify axis order and units, and retain the chosen CRS in output metadata.
• I/O: compare storage location, row-group size and compression on representative data. Use local NVMe only when available, and measure transfer time as well as reads.
• Precision: measure memory and runtime for an accuracy level validated against the reference; do not assume one data type is always faster.
• Logging: time each stage (load, filter, PIP) separately; it helps you see bottlenecks.

9) Troubleshooting

CUDA error or no GPU
Check nvidia-smi inside the container. Verify the host runtime, assigned devices, driver compatibility and image settings; environment variables alone do not establish GPU access.

Memory exhausted
Reduce partition size and account for the candidate and output structures, not just the point table.

Wrong results
Check CRS, axis order, valid closed rings, holes, boundary policy and identifier alignment after filtering or sorting.

Slow reads
Measure transfer, reading and conversion separately. Test storage, format and row-group changes on a representative sample before converting the full dataset.

Methods record

Preserve the tested image digest and dependency lock, input schemas, geometry conversion, index settings, output identifiers, validation fixtures and timings. Record that cuSpatial is a legacy dependency. This checklist is not an install command or an executable configuration.

Related reading

• Scientific modeling on cloud GPUs — what works, what doesn’t

Try Compute today

Use custom templates to reuse a tested container configuration. Check software compatibility and available capacity separately. Back up data outside the instance and check the current restart and retention conditions before stopping it.

‍