AGENT SKILL

optimize-for-gpu

GPU-accelerates scientific Python on NVIDIA hardware and verifies that the result is correct and faster. Use for CUDA/GPU optimization; CPU-bound NumPy, SciPy, pandas, scikit-learn, NetworkX, scikit-image, vector-search, image-processing, graph, simulation, or file-I/O workloads; CuPy, cuDF, cuML, cuGraph, cuVS, cuCIM, KvikIO, Warp, Newton, Numba-CUDA, or RAFT questions; and profiling, memory-transfer, kernel, or multi-GPU bottlenecks. Also use when large data-parallel Python code is slow and GPU acceleration is a plausible option, even if the user does not name CUDA.

License 许可
MIT
最近更新
2026-11-14
Stars
★ 132
Forks
16

01 前言 Front Matter

name
optimize-for-gpu
license
MIT
metadata
{ "tags": "GPU acceleration, CUDA, performance optimization, scientific Python", "version": "1.4", "category": "data-science-and-ml", "maintainer": "Kalaris Labs" }
description
GPU-accelerates scientific Python on NVIDIA hardware and verifies that the result is correct and faster. Use for CUDA/GPU optimization; CPU-bound NumPy, SciPy, pandas, scikit-learn, NetworkX, scikit-image, vector-search, image-processing, graph, simulation, or file-I/O workloads; CuPy, cuDF, cuML, cuGraph, cuVS, cuCIM, KvikIO, Warp, Newton, Numba-CUDA, or RAFT questions; and profiling, memory-transfer, kernel, or multi-GPU bottlenecks. Also use when large data-parallel Python code is slow and GPU acceleration is a plausible option, even if the user does not name CUDA.
compatibility
Requires an NVIDIA CUDA-capable GPU for GPU execution. RAPIDS 26.06 requires Python 3.11+ on Linux or WSL2 and matching CUDA 12 or 13 wheels. Package installation needs network access.

02 资源文件 15

03 SKILL.md 正文

GPU Optimization for Python with NVIDIA

Treat GPU acceleration as an evidence-driven optimization, not an automatic rewrite. Preserve the user's numerical and algorithmic contract, measure with representative data, and keep the GPU version only when synchronized end-to-end benchmarks show a useful improvement.

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

Choose the Smallest Suitable Layer

Prefer a maintained library implementation over a custom kernel:

Existing workload Preferred path Use for
NumPy / SciPy CuPy arrays, sparse matrices, linear algebra, FFTs, signal processing
pandas cudf.pandas, then cuDF accelerator mode first; native API for more control
scikit-learn cuml.accel, then cuML accelerator mode first; native estimators as needed
NetworkX nx-cugraph, then cuGraph backend dispatch first; native graph API at scale
scikit-image cuCIM GPU image processing and whole-slide imaging
Faiss / Annoy / k-NN cuVS exact and approximate vector search
Raw or remote file I/O KvikIO GPU buffers and GPUDirect Storage
Custom array kernels Numba-CUDA-MLIR for new work; Numba-CUDA for existing code explicit SIMT kernels and shared memory
Spatial or differentiable kernels Warp geometry, simulation kernels, robotics, autodiff
High-level physics simulation Newton maintained engine that succeeds the removed warp.sim module
Low-level RAPIDS primitives RAFT (pylibraft) sparse eigensolvers, resources, multi-GPU building blocks

Do not move code out of PyTorch, JAX, TensorFlow, or another GPU-native framework merely to use one of these libraries. First remove CPU round trips and use the framework's compiler, profiler, mixed-precision, and batching facilities.

Treat these as legacy-only:

Project Status Guidance
cuxfilter Final release 26.06 Maintain existing dashboards only. For new work, combine cuDF with HoloViews/hvPlot/Datashader and serve with Panel, Dash, Streamlit, or Bokeh.
cuSpatial Archived at 25.04 Use only in an isolated legacy environment. For new work, keep geometry in GeoPandas/Shapely and accelerate compatible tabular stages with cuDF.

Full per-library guidance, including when each is the wrong choice and how to combine them, is in references/decision_framework.md. Install commands and CUDA version selection are in references/installation.md. Before/after conversions for every library are in references/code_transformation_patterns.md.

Optimization Workflow

1. Define the contract and baseline

  • Capture a representative input, expected output, and acceptable numerical tolerance.
  • Measure the current end-to-end path, including input, transfers, compute, and output.
  • Profile before changing code. Use CPU profilers for CPU code and identify whether the real limit is compute, memory bandwidth, allocation, transfer, synchronization, or storage.
  • Record hardware, package versions, dtypes, shapes, batch size, and warm-up policy with results.

2. Check suitability before porting

GPU execution is promising when the hot path exposes substantial independent work, runs often enough to amortize initialization and transfer, and has a working set that fits available device memory with room for temporaries. Keep a CPU path when the workload is small, mostly sequential, dominated by unsupported operations, or requires frequent host-device round trips.

Do not use fixed row-count thresholds as proof. Benchmark the user's actual shapes and hardware. For out-of-core data, estimate peak working memory and choose chunking, Dask, or a streaming design before allocating.

3. Try the least disruptive implementation

  1. If the code already uses a GPU-native framework, optimize within that framework.
  2. Try accelerator or backend modes (cudf.pandas, cuml.accel, nx-cugraph).
  3. Move to a native GPU API only where accelerator coverage or performance is insufficient.
  4. Write a custom kernel only when profiling shows an operation without a suitable library implementation.

Read the relevant library reference before writing code; compatible names can still differ in defaults, dtypes, output types, and supported arguments.

4. Keep a coherent GPU data path

  • Transfer inputs once and keep intermediates device-resident.
  • Reuse allocations and prefer out= or in-place forms when semantics allow.
  • Batch small operations; fuse elementwise work when it removes intermediate arrays.
  • Use pinned host memory and non-default streams only after profiling shows transfer overlap matters.
  • Choose float32, mixed precision, or reduced-precision storage only when the contract permits it.

5. Validate semantics before speed

  • Compare CPU and GPU outputs on small deterministic fixtures and representative data.
  • Use explicit tolerances for floating-point results and test edge cases, NaNs, ordering, and dtypes.
  • For approximate nearest-neighbor indexes, report recall@k against exact search; do not compare an exact CPU algorithm with an approximate GPU algorithm as if they were equivalent.
  • Check accelerator warnings and logs for CPU fallback.

6. Benchmark GPU code correctly

GPU work is asynchronous, so a CPU timer around an unsynchronized call measures enqueue time. Warm up context creation and JIT compilation, then use CUDA events or a library-aware timer:

from cupyx.profiler import benchmark

print(benchmark(gpu_function, (arg1, arg2), n_warmup=10, n_repeat=100))

Use %gpu_timeit in notebooks, Nsight Systems (nsys) for end-to-end timelines, and Nsight Compute (ncu) for kernel analysis. Report both synchronized kernel/region time and realistic end-to-end latency; include transfer and conversion costs when production pays them.

7. Keep, revise, or reject the port

Retain the GPU path only when it passes correctness checks and improves the metric the user cares about on representative data. If it does not, explain whether the limiting factor is problem size, transfers, unsupported fallback, memory pressure, launch granularity, or the algorithm itself.

Important Notes

  • Provide a CPU fallback when the application requires portability; otherwise fail early with a clear hardware and dependency error.
  • 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
  • Prefer the CUDA Array Interface or DLPack for supported zero-copy interchange, but verify device, dtype, contiguity, ownership, and stream semantics rather than assuming every conversion is free.

Reference Files

Before writing any GPU optimization code, read the relevant reference file(s):

File When to Read
references/cupy.md User has NumPy/SciPy code, or needs array operations on GPU
references/numba.md User has existing Numba-CUDA code or needs explicit SIMT kernels; note the migration path to Numba-CUDA-MLIR
references/cudf.md User has pandas code, or needs dataframe operations on GPU
references/cuml.md User has scikit-learn code, or needs ML training/inference/preprocessing on GPU
references/cugraph.md User has NetworkX code, or needs graph analytics on GPU
references/warp.md User needs GPU kernels for simulation, spatial computing, mesh/volume queries, differentiable programming, or robotics; use Newton for a high-level physics engine
references/kvikio.md User needs high-performance file IO to/from GPU, GPUDirect Storage, reading S3/HTTP to GPU, or Zarr on GPU
references/cuxfilter.md User maintains or explicitly requests cuxfilter (sunset — 26.06 is the final release)
references/cucim.md User has scikit-image code, or needs image processing, digital pathology, or WSI reading on GPU
references/cuvs.md User needs vector search, nearest neighbors, similarity search, or RAG retrieval on GPU
references/cuspatial.md User maintains or explicitly requests cuSpatial (archived — frozen at 25.04 and isolated from current RAPIDS)
references/raft.md User needs sparse eigensolvers, device memory management, or multi-GPU primitives

Read the specific reference before writing code — they contain detailed API patterns, optimization techniques, and pitfalls specific to each library.

Related skills

  • dask: Distributed computing for larger-than-RAM pandas/NumPy workflows.

04 同仓库更多 Skills

KalarisLabs
KalarisLabs/research-agent-skills

plos

Prepare manuscripts for PLOS journals (PLOS ONE, PLOS Biology, PLOS Computational Biology, PLOS Genetics, PLOS Medicine, PLOS Pathogens, PLOS Neglected Tropical Diseases, PLOS Global Public Health and others), covering structure, abstract and author summary, Vancouver-style references, the mandatory data availability policy, ethics and financial disclosure statements, figure requirements (PACE), the PLOS LaTeX template, reporting guidelines and PLOS ONE's publication criteria. Use when targeting any PLOS journal or checking compliance with PLOS policies.

★ 132
KalarisLabs
KalarisLabs/research-agent-skills

pkpd-modeling

Pharmacokinetic and pharmacodynamic modelling and simulation - non-compartmental analysis, compartmental and population PK, PK/PD and exposure-response, TMDD, PBPK orientation, bioequivalence, allometric scaling and first-in-human dose, drug interaction prediction, and Bayesian therapeutic drug monitoring. Use when analysing concentration-time data, deriving exposure metrics, fitting PK or PD models, or evaluating dosing regimens. Triggers include "pharmacokinetics", "pharmacodynamics", "PK/PD", "NCA", "non-compartmental", "AUC", "Cmax", "lambda z", "half-life", "clearance", "volume of distribution", "compartmental model", "population PK", "popPK", "NONMEM", "nlmixr2", "Pharmpy", "Monolix", "exposure-response", "Emax", "EC50", "indirect response", "effect compartment", "TMDD", "PBPK", "bioequivalence", "RSABE", "ABEL", "allometric scaling", "first-in-human", "MABEL", "drug-drug interaction", "DDI", "ICH M12", "concentration-QTc", "therapeutic drug monitoring", "MIPD", and "dosing regimen".

★ 132
KalarisLabs
KalarisLabs/research-agent-skills

pinecone

Guides use of Pinecone, a managed serverless vector database, through its Python client and the LangChain and LlamaIndex integrations. Covers creating indexes, upserting and querying vectors, metadata filtering, namespaces, hybrid dense and sparse search, index management, and deleting vectors. Use when building a production RAG system on a hosted vector store, adding semantic search or recommendations without running infrastructure, isolating per-user or per-tenant data with namespaces, combining dense and sparse vectors in one query, or filtering results by metadata. Do not use for self-hosted or local stores (Chroma, Weaviate) or offline similarity search (FAISS).

★ 132
KalarisLabs
KalarisLabs/research-agent-skills

pi-agent

Build with and use Pi, the minimal terminal coding harness. Use for installing Pi, configuring providers/models/settings/environment variables, creating Pi skills/extensions/packages/themes/prompt templates, embedding Pi through the SDK, integrating over RPC or JSON event streams, parsing sessions, running local models through the llama.cpp router, developing custom Pi providers and TUI components, or using ecosystem packages such as pi-subagents (delegation/orchestration), pi-mcp-adapter (MCP servers), pi-interview (interactive forms), and pi-web-access (web search, fetching, video understanding).

★ 132
KalarisLabs
KalarisLabs/research-agent-skills

phoenix-observability

Open-source AI observability platform for LLM tracing, evaluation, and monitoring. Use when debugging LLM applications with detailed traces, running evaluations on datasets, or monitoring production AI systems with real-time insights.

★ 132
KalarisLabs
KalarisLabs/research-agent-skills

peft-fine-tuning

Fine-tunes LLMs with Hugging Face PEFT, using LoRA, QLoRA, IA3, AdaLoRA, prefix tuning, and prompt tuning so that under 1% of parameters are trained. Covers rank, alpha, and target module selection, loading and merging adapters, multi-adapter serving, and integration with TRL SFTTrainer, Axolotl, and vLLM. Use when fine-tuning 7B-70B models on limited GPU memory, when running QLoRA on a single 24GB GPU, when choosing LoRA rank and alpha, when merging or swapping adapters on one base model, or when debugging CUDA OOM or an adapter that does not apply. Not for full fine-tuning of small models under 1B parameters or cases needing all weights updated.

★ 132