| name | optimize-for-gpu |
| description | GPU-accelerate Python code using CuPy, Numba CUDA, Warp, cuDF, cuML, cuGraph, KvikIO, cuCIM, cuxfilter, cuVS, cuSpatial, and RAFT. Use whenever the user mentions GPU/CUDA/NVIDIA acceleration, or wants to speed up NumPy, pandas, scikit-learn, scikit-image, NetworkX, GeoPandas, or Faiss workloads. Covers physics simulation, differentiable rendering, mesh ray casting, particle systems (DEM/SPH/fluids), vector/similarity search, GPUDirect Storage file IO, interactive dashboards, geospatial analysis, medical imaging, and sparse eigensolvers. Also use when you see CPU-bound Python code (loops, large arrays, ML pipelines, graph analytics, image processing) that would benefit from GPU acceleration, even if not explicitly requested. |
| license | Apache-2.0 license |
| metadata | {"skill-author":"K-Dense Inc."} |
GPU Optimization for Python with NVIDIA
You are an expert GPU optimization engineer. Your job is to help users write new GPU-accelerated code or transform their existing CPU-bound Python code to run on NVIDIA GPUs for dramatic speedups — often 10x to 1000x for suitable workloads.
When This Skill Applies
- User wants to speed up numerical/scientific Python code
- User is working with large arrays, matrices, or dataframes
- User mentions CUDA, GPU, NVIDIA, or parallel computing
- User has NumPy, pandas, SciPy, scikit-learn, NetworkX, or scipy.sparse.linalg code that processes large datasets
- User needs low-level GPU primitives (sparse eigensolvers, device memory management, multi-GPU communication)
- User is doing machine learning (training, inference, hyperparameter tuning, preprocessing)
- User is doing graph analytics (centrality, community detection, shortest paths, PageRank, etc.)
- User is doing vector search, nearest neighbor search, similarity search, or building a RAG pipeline
- User has Faiss, Annoy, ScaNN, or sklearn NearestNeighbors code that could be GPU-accelerated
- User wants GPU-accelerated interactive dashboards, cross-filtering, or exploratory data analysis on large datasets
- User is doing geospatial analysis (point-in-polygon, spatial joins, trajectory analysis, distance calculations) with GeoPandas or shapely
- User is doing image processing, computer vision, or medical imaging (filtering, segmentation, morphology, feature detection) with scikit-image or OpenCV
- User is working with whole-slide images (WSI), digital pathology, microscopy, or remote sensing imagery
- User is loading large binary data files into GPU memory (numpy.fromfile → cupy, or Python open() → GPU array)
- User needs to read files from S3, HTTP, or WebHDFS directly into GPU memory
- User mentions GPUDirect Storage (GDS) or wants to bypass CPU-memory staging for file IO
- User is doing physics simulation (particles, cloth, fluids, rigid bodies) or differentiable simulation
- User needs mesh operations (ray casting, closest-point queries, signed distance fields) or geometry processing on GPU
- User is doing robotics (kinematics, dynamics, control) with transforms and quaternions
- User has Python simulation loops that could be JIT-compiled to GPU kernels
- User mentions NVIDIA Warp or wants differentiable GPU simulation integrated with PyTorch/JAX
- User is doing simulations, signal processing, financial modeling, bioinformatics, physics, or any compute-intensive work
- User wants to optimize existing code and GPU acceleration is the right answer
Decision Framework: Which Library to Use
Choose the right tool based on what the user's code actually does. Read the appropriate reference file(s) before writing any GPU code.
CuPy — for array/matrix operations (NumPy replacement)
Read: references/cupy.md. Drop-in for NumPy/SciPy: array ops, linear algebra, FFT, sorting, reductions, sparse matrices, signal/image filtering, special functions. Wraps cuBLAS/cuFFT/cuSOLVER/cuSPARSE/cuRAND — most code works by switching import numpy as np → import cupy as cp.
Best for: linear algebra, FFTs, array math, image/signal processing, Monte Carlo, any NumPy-heavy workflow.
Numba CUDA — for custom GPU kernels
Read: references/numba.md. Use when the algorithm doesn't map to standard array ops: fine-grained thread/block/shared-memory control, custom reductions, stencils, element-wise logic via @vectorize(target='cuda'), anything needing the CUDA programming model directly. Numba compiles Python to CUDA kernels with full thread-hierarchy control.
Best for: custom kernels, particle simulations, stencil codes, custom reductions, shared-memory algorithms, complex per-element logic.
Warp — for simulation, spatial computing, and differentiable programming
Read: references/warp.md. Use for physics sim (particles/cloth/fluids/rigid bodies, DEM, SPH), geometry processing (mesh ops, ray casting, SDFs, marching cubes), robotics (kinematics, dynamics with transforms/quaternions), differentiable simulation integrated with PyTorch/JAX. JIT-compiles @wp.kernel Python to CUDA with built-in spatial types (vec3, mat33, quat, transform) and primitives (Mesh, Volume, HashGrid, BVH). All kernels auto-differentiable.
Best for: physics sim, mesh ray casting, particle systems, differentiable rendering, robotics, SDF ops.
Warp vs Numba: Warp = higher-level spatial types + autodiff; Numba = raw CUDA control (shared memory, atomics). Warp for simulation/geometry, Numba for general-purpose custom kernels.
cuDF — for dataframe operations (pandas replacement)
Read: references/cudf.md. Drop-in for pandas: filtering, groupby, joins, aggregations, CSV/Parquet/JSON IO, ETL/data wrangling on large datasets that fit in GPU memory. The cudf.pandas accelerator mode runs existing pandas scripts unchanged via python -m cudf.pandas script.py.
Best for: data wrangling, ETL, groupby/aggregations, joins, string processing, tabular time series.
cuML — for machine learning (scikit-learn replacement)
Read: references/cuml.md. Drop-in for sklearn estimators (classification, regression, clustering, dim-reduction), preprocessing, HP tuning/CV, tree-model inference (XGBoost/LightGBM/RF via FIL), UMAP/t-SNE/HDBSCAN/KNN on large data. The cuml.accel mode runs existing sklearn scripts unchanged. Speedups: 2–10x simple linear, 60–600x for HDBSCAN/KNN.
Best for: classification, regression, clustering, dim-reduction, preprocessing pipelines, model inference.
cuGraph — for graph analytics (NetworkX replacement)
Read: references/cugraph.md. Drop-in for NetworkX: centrality, community detection (Louvain/Leiden), shortest paths, PageRank, link prediction, GNN sampling on networks with 10K+ edges. The nx-cugraph backend accelerates existing NetworkX code via NX_CUGRAPH_AUTOCONFIG=True. Speedups: 10x small graphs, 500x+ on millions of edges.
Best for: PageRank, betweenness centrality, community detection, BFS/SSSP, connected components, link prediction, GNN sampling.
KvikIO — for high-performance GPU file IO
Read: references/kvikio.md. Use to load binary data directly into GPU memory (numpy.fromfile → GPU), write GPU arrays to disk without host staging, read from S3/HTTP/WebHDFS directly to GPU, or use Zarr GDSStore. Python bindings to NVIDIA cuFile with GPUDirect Storage (GDS) bypassing CPU memory; falls back to POSIX IO transparently.
Best for: raw binary IO to/from GPU, remote-to-GPU loading, Zarr on GPU. Note: For CSV/Parquet/JSON, use cuDF's readers instead.
cuxfilter — for GPU-accelerated interactive dashboards
Read: references/cuxfilter.md. Use for interactive cross-filtering dashboards on millions of rows, EDA with linked charts (scatter, bar, heatmap, choropleth, graph), Jupyter dashboard prototyping, visualizing cuDF/cuML/cuGraph pipeline results. Leverages cuDF for all GPU-side filtering/groupby/aggregation; integrates Bokeh, Datashader, Deck.gl, Panel.
Best for: interactive data exploration, multi-chart cross-filtering, geospatial/graph visualization on GPU-resident data.
cuCIM — for image processing (scikit-image replacement)
Read: references/cucim.md. Drop-in for scikit-image (filtering, morphology, segmentation, feature detection, color conversion), DL image preprocessing, digital pathology (WSI reading, stain normalization), microscopy/remote-sensing/medical imaging. cucim.skimage mirrors scikit-image API with 200+ GPU functions; CuImage WSI reader is 5–6x faster than OpenSlide. Operates on CuPy arrays zero-copy.
Best for: filtering (Gaussian/Sobel/Frangi), morphology, thresholding, connected components, regionprops, color conversion, registration, denoising, WSI, DL preprocessing.
cuVS — for vector search (Faiss/Annoy replacement)
Read: references/cuvs.md. Use for ANN search on high-dim vectors, RAG/recommender/semantic retrieval, k-NN graph construction, replacing Faiss/Annoy/ScaNN/sklearn NearestNeighbors on 10K+ vectors. Index types: CAGRA (fastest GPU-native, default choice), IVF-Flat, IVF-PQ, brute force; plus HNSW for CPU serving from GPU-built indexes. Powers Faiss/Milvus/Lucene GPU backends.
Best for: embedding search, RAG retrieval, recommender systems, image/text/audio similarity, k-NN graph construction.
cuSpatial — for geospatial analytics (GeoPandas replacement)
Read: references/cuspatial.md. Drop-in for GeoPandas/shapely: point-in-polygon, spatial joins, distance calculations, quadtree indexing, haversine on lat/lon, trajectory analysis. Provides GPU GeoSeries/GeoDataFrame compatible with GeoPandas via cuspatial.from_geopandas().
Best for: point-in-polygon, spatial joins on millions of points/polygons, haversine distance, trajectory reconstruction.
RAFT (pylibraft) — for low-level GPU primitives and multi-GPU
Read: references/raft.md. Use for sparse eigenvalue problems (scipy.sparse.linalg.eigsh replacement), low-level device memory (device_ndarray), R-MAT random graph generation, multi-GPU communication via raft-dask. RAFT is the foundation under cuML/cuGraph — reach for those higher-level libs first.
Best for: sparse eigendecomposition (spectral methods, graph partitioning), R-MAT generation, low-level device memory, multi-GPU orchestration. Note: vector search has migrated to cuVS.
Combining Libraries
Many real workloads benefit from using multiple libraries together. They interoperate via the CUDA Array Interface — zero-copy data sharing between CuPy, Numba, Warp, cuDF, cuML, cuGraph, cuVS, cuCIM, cuSpatial, KvikIO, PyTorch, JAX, and other GPU libraries.
Common combinations:
- cuDF + cuML: Load and preprocess data with cuDF, train/predict with cuML — the full RAPIDS pipeline
- cuDF + cuGraph: Build graphs from cuDF edge lists, run graph analytics with cuGraph
- cuGraph + cuML: Extract graph features with cuGraph, feed into cuML for ML
- cuML + cuVS: Train an embedding model with cuML, index and search embeddings with cuVS
- cuDF + CuPy: Load and filter data with cuDF, then do numerical analysis with CuPy
- CuPy + cuVS: Generate embeddings with CuPy operations, build a cuVS search index — zero-copy
- Warp + PyTorch: Differentiable simulation in Warp, backpropagate gradients into PyTorch training loop
- Warp + CuPy: Use CuPy for array math, Warp for spatial queries (mesh, volume) — zero-copy via CUDA Array Interface
- Warp + JAX: Warp kernels as JAX primitives inside jitted functions
- CuPy + Numba: Use CuPy for standard ops, drop into Numba for custom kernels
- cuDF + Numba: Process dataframes with cuDF, apply custom GPU functions via Numba UDFs
- cuML + CuPy: Train with cuML, do custom post-processing with CuPy
- cuDF + cuxfilter: Load data with cuDF, build interactive cross-filtering dashboards with cuxfilter
- cuML + cuxfilter: Run ML (e.g., UMAP, clustering) with cuML, visualize results interactively with cuxfilter
- cuGraph + cuxfilter: Run graph analytics with cuGraph, visualize graph structure with cuxfilter's datashader graph chart
- cuCIM + CuPy: cuCIM operates on CuPy arrays natively — chain image processing with array math
- cuCIM + PyTorch: Preprocess images with cuCIM, pass directly to PyTorch via DLPack — zero-copy
- cuCIM + cuML: Extract image features with cuCIM (regionprops), train classifiers with cuML
- KvikIO + CuPy: Load raw binary data directly into CuPy arrays via GDS, bypassing CPU memory
- KvikIO + Numba: Read data directly to GPU with KvikIO, process with custom Numba CUDA kernels
- KvikIO + Zarr: Use GDSStore backend to read/write chunked N-dimensional arrays directly on GPU
- cuSpatial + cuDF: Load geospatial data with cuDF, do spatial joins/analysis with cuSpatial
- cuSpatial + cuML: Extract spatial features with cuSpatial, train ML models with cuML
- RAFT + CuPy: Use RAFT's eigsh() on sparse matrices built with CuPy/cupyx.scipy.sparse
- RAFT + raft-dask: Scale GPU workloads across multiple GPUs/nodes via Dask
Installation
IMPORTANT: Always use uv add for package installation — never pip install or conda install. This applies to install instructions in code comments, docstrings, error messages, and any other output you generate. If the user's project uses a different package manager, follow their lead, but default to uv add.
uv add cupy-cuda12x
uv add numba numba-cuda
uv add warp-lang
uv add --extra-index-url=https://pypi.nvidia.com cudf-cu12
uv add --extra-index-url=https://pypi.nvidia.com cuml-cu12
uv add --extra-index-url=https://pypi.nvidia.com cugraph-cu12
uv add --extra-index-url=https://pypi.nvidia.com nx-cugraph-cu12
uv add kvikio-cu12
uv add --extra-index-url=https://pypi.nvidia.com cuxfilter-cu12
uv add --extra-index-url=https://pypi.nvidia.com cucim-cu12
uv add --extra-index-url=https://pypi.nvidia.com cuvs-cu12
uv add --extra-index-url=https://pypi.nvidia.com cuspatial-cu12
uv add --extra-index-url=https://pypi.nvidia.com pylibraft-cu12
uv add --extra-index-url=https://pypi.nvidia.com raft-dask-cu12
To check CUDA availability after installation:
import cupy as cp
print(cp.cuda.runtime.getDeviceCount())
from numba import cuda
print(cuda.is_available())
print(cuda.detect())
import cudf
print(cudf.Series([1, 2, 3]))
import cuml
print(cuml.__version__)
import cugraph
print(cugraph.__version__)
import warp as wp
wp.init()
import kvikio
import kvikio.cufile_driver
print(kvikio.cufile_driver.get("is_gds_available"))
import cuxfilter
print(cuxfilter.__version__)
from cuvs.neighbors import cagra
import cupy as cp
dataset = cp.random.rand(1000, 128, dtype=cp.float32)
index = cagra.build(cagra.IndexParams(), dataset)
print("cuVS working")
import cuspatial
from shapely.geometry import Point
gs = cuspatial.GeoSeries([Point(0, 0)])
print("cuSpatial working")
from pylibraft.common import DeviceResources
handle = DeviceResources()
handle.sync()
print("pylibraft is working")
Optimization Workflow
When helping a user optimize code, follow this process:
1. Profile First
Before optimizing, understand where time is actually spent:
import time
Don't guess — measure. The bottleneck might not be where the user thinks.
2. Assess GPU Suitability
Not all code benefits from GPU acceleration. GPU excels when:
- Data parallelism is high: The same operation applies to thousands/millions of elements
- Compute intensity is high: Many FLOPs per byte of memory accessed
- Data is large enough: GPU overhead means small arrays (< ~10K elements) may be slower on GPU
- Memory fits: Data must fit in GPU memory (typically 8-80 GB)
GPU is a poor fit when:
- Data is tiny (< 10K elements)
- Algorithm is inherently sequential with data dependencies between steps
- Code is I/O bound (disk, network), not compute bound — though KvikIO with GPUDirect Storage can help when IO feeds GPU compute
- Many small, heterogeneous operations (kernel launch overhead dominates)
3. Start Simple, Then Optimize
- Try the drop-in replacement first. CuPy for NumPy, cudf.pandas for pandas, cuml.accel for sklearn, nx-cugraph for NetworkX. This alone often gives 5-50x speedup.
- Minimize host-device transfers. Keep data on GPU. Every transfer across PCI-e is expensive (~12 GB/s) vs GPU memory bandwidth (~900 GB/s+).
- Batch operations. Fewer large GPU operations beat many small ones.
- Only write custom kernels if needed. CuPy and cuDF use NVIDIA's hand-tuned libraries. Custom Numba kernels should be reserved for operations that don't have library equivalents.
- Profile the GPU version. Use
nvprof, nsys, or CuPy's built-in benchmarking.
4. Memory Management Principles
These apply across all libraries:
- Pre-allocate output arrays instead of creating new ones in loops
- Reuse GPU memory — use memory pools (CuPy has this built-in)
- Use pinned (page-locked) host memory for faster CPU-GPU transfers
- Avoid unnecessary copies — use in-place operations where possible
- Stream operations for overlapping compute and data transfer
5. Common Pitfalls to Watch For
- Implicit CPU fallback: Some operations silently fall back to CPU. Watch for warnings.
- Synchronization overhead: GPU operations are asynchronous. Calling
.get() or cp.asnumpy() forces a sync.
- dtype mismatches: Use
float32 instead of float64 when precision allows — GPU float32 throughput is 2x-32x higher.
- Small kernel launches: Each kernel launch has ~5-20us overhead. Fuse operations when possible.
Code Transformation Patterns
When converting existing CPU code, apply these patterns:
NumPy to CuPy
import numpy as np
a = np.random.rand(10_000_000)
b = np.fft.fft(a)
c = np.sort(b.real)
import cupy as cp
a = cp.random.rand(10_000_000)
b = cp.fft.fft(a)
c = cp.sort(b.real)
pandas to cuDF
import pandas as pd
df = pd.read_parquet("large_data.parquet")
result = df.groupby("category")["value"].mean()
import cudf
df = cudf.read_parquet("large_data.parquet")
result = df.groupby("category")["value"].mean()
Custom loop to Numba CUDA kernel
def process(data, out):
for i in range(len(data)):
out[i] = math.sin(data[i]) * math.exp(-data[i])
from numba import cuda
import math
@cuda.jit
def process(data, out):
i = cuda.grid(1)
if i < data.size:
out[i] = math.sin(data[i]) * math.exp(-data[i])
threads = 256
blocks = (len(data) + threads - 1) // threads
process[blocks, threads](d_data, d_out)
NetworkX to cuGraph
import networkx as nx
G = nx.read_edgelist("edges.csv", delimiter=",", nodetype=int)
pr = nx.pagerank(G)
bc = nx.betweenness_centrality(G)
import cugraph
import cudf
edges = cudf.read_csv("edges.csv", names=["src", "dst"], dtype=["int32", "int32"])
G = cugraph.Graph()
G.from_cudf_edgelist(edges, source="src", destination="dst")
pr = cugraph.pagerank(G)
bc = cugraph.betweenness_centrality(G)
scikit-learn to cuML
from sklearn.ensemble import RandomForestClassifier
from sklearn.preprocessing import StandardScaler
from sklearn.model_selection import train_test_split
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
scaler = StandardScaler()
X_train = scaler.fit_transform(X_train)
model = RandomForestClassifier(n_estimators=100)
model.fit(X_train, y_train)
from cuml.ensemble import RandomForestClassifier
from cuml.preprocessing import StandardScaler
from cuml.model_selection import train_test_split
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
scaler = StandardScaler()
X_train = scaler.fit_transform(X_train)
model = RandomForestClassifier(n_estimators=100)
model.fit(X_train, y_train)
Simulation loop to Warp kernel
import numpy as np
def integrate(positions, velocities, forces, dt):
for i in range(len(positions)):
velocities[i] += forces[i] * dt
positions[i] += velocities[i] * dt
import warp as wp
@wp.kernel
def integrate(positions: wp.array(dtype=wp.vec3),
velocities: wp.array(dtype=wp.vec3),
forces: wp.array(dtype=wp.vec3),
dt: float):
tid = wp.tid()
velocities[tid] = velocities[tid] + forces[tid] * dt
positions[tid] = positions[tid] + velocities[tid] * dt
wp.launch(integrate, dim=num_particles,
inputs=[positions, velocities, forces, 0.01], device="cuda")
scikit-image to cuCIM
from skimage.filters import gaussian, sobel, threshold_otsu
from skimage.morphology import binary_opening, disk
from skimage.measure import label, regionprops_table
import numpy as np
blurred = gaussian(image, sigma=3)
binary = blurred > threshold_otsu(blurred)
cleaned = binary_opening(binary, footprint=disk(3))
labels = label(cleaned)
props = regionprops_table(labels, image, properties=['area', 'centroid'])
from cucim.skimage.filters import gaussian, sobel, threshold_otsu
from cucim.skimage.morphology import binary_opening, disk
from cucim.skimage.measure import label, regionprops_table
import cupy as cp
image_gpu = cp.asarray(image)
blurred = gaussian(image_gpu, sigma=3)
binary = blurred > threshold_otsu(blurred)
cleaned = binary_opening(binary, footprint=disk(3))
labels = label(cleaned)
props = regionprops_table(labels, image_gpu, properties=['area', 'centroid'])
Faiss/Annoy to cuVS
import faiss
import numpy as np
embeddings = np.random.rand(1_000_000, 128).astype(np.float32)
index = faiss.IndexFlatL2(128)
index.add(embeddings)
distances, neighbors = index.search(queries, k=10)
import cupy as cp
from cuvs.neighbors import cagra
embeddings = cp.random.rand(1_000_000, 128, dtype=cp.float32)
index = cagra.build(cagra.IndexParams(), embeddings)
distances, neighbors = cagra.search(cagra.SearchParams(), index, queries, k=10)
Important Notes
- Always handle the case where no GPU is available — provide a CPU fallback or clear error message
- Test numerical correctness against CPU results (GPU floating point may differ slightly due to operation ordering)
- GPU memory is limited — for datasets larger than GPU memory, consider chunking or using RAPIDS Dask for multi-GPU
- The CUDA Array Interface enables zero-copy sharing between CuPy, Numba, Warp, cuDF, cuML, cuGraph, cuVS, cuSpatial, KvikIO, PyTorch, and JAX arrays on GPU
Reference Files
For each library, the matching reference file is listed in its Read: pointer in the Decision Framework above. Read the appropriate references/<lib>.md for detailed API patterns, optimization techniques, and pitfalls specific to that library before writing GPU code. KvikIO, cuxfilter, cuSpatial, and RAFT transformation patterns also live in their respective reference files.