Rapids First

RAPIDS-first

When to Enable

Enable this skill if and only if the user's request explicitly contains rapids-first (or the synonymous wording "RAPIDS first"). Do not apply it proactively in other scenarios, to avoid modifying code outside the user's expectations.

This skill covers four packages: cupy, cupyx, cudf, cuml.

Applicable Scenarios

Once rapids-first is enabled, all "writing Python code" subtasks are handled according to the RAPIDS-first principle, not limited to rewriting existing CPU code:

1. Rewriting existing CPU code: replace numpy / pandas / sklearn / scipy / umap-learn / hdbscan / faiss calls with the corresponding RAPIDS APIs.
2. Adding new features / implementing new algorithms: when writing implementations from scratch, prefer RAPIDS APIs as the foundation rather than numpy / scipy / sklearn. Example: for matrix decomposition → directly choose cuml.decomposition over sklearn.decomposition; for nearest neighbors → directly choose cuml.neighbors.NearestNeighbors over faiss / sklearn.neighbors; for sparse iterative solves → directly choose cupyx.scipy.sparse.linalg over scipy.sparse.linalg.
3. Creating new scripts (ETL / training / inference / batch processing): use cudf.read_csv / cudf.read_parquet / cudf.read_orc / cudf.read_json for data loading, cupy for matrix computation, cudf + cuml.preprocessing for feature engineering, cuml for model training and prediction, cupyx.scipy.ndimage / cupyx.scipy.signal for image-style filtering and signal processing.
4. Adding new tests: use RAPIDS as much as possible for test data generation and assertion comparison (cudf.testing / cuml.testing / cupy.testing, plus cuml.datasets.make_blobs and cupy.random for synthetic data); let numpy / pandas appear only for RAPIDS↔CPU numerical comparisons, with a one-shot conversion at the boundary.
5. Fixing bugs: even when just fixing a single numpy function call, if a suitable RAPIDS equivalent exists in the context, replace it in passing.

In short: after enabling this skill, "think first how to do it with RAPIDS" takes priority over "think first how to do it with numpy / pandas / sklearn". Only fall back to the CPU path when the RAPIDS stack truly has no corresponding implementation.

Three Core Principles

1. Zero-code acceleration first: this stack ships two monkey-patch accelerators. cudf.pandas covers pandas, and cuml.accel covers scikit-learn and umap-learn (plus the standalone hdbscan package when the user has installed it). Both let existing CPU code run on GPU without changing any imports. Use zero-code whenever possible — especially in the "rewriting existing CPU code" scenario.
2. Avoid redundant CPU↔GPU conversions: once data is on GPU, keep it on GPU as much as possible, minimizing calls like .to_pandas() / .to_numpy() / .get() that trigger device synchronization and copying; only do a one-shot downlink at the pipeline endpoint or at necessary output/visualization boundaries. Mixing cupy.ndarray with numpy.ndarray (or cudf.DataFrame with pandas.DataFrame) triggers implicit synchronization and should be proactively eliminated.
3. Precise API targeting: this skill directory ships a complete API index apis/<pkg>.txt for each RAPIDS package, with each line formatted as "full path(signature) - first line of docstring". A single ripgrep search retrieves both the call syntax and purpose, avoiding writing signatures from memory (cuML and sklearn often differ in parameter order, default values, output_type, etc.).

Directory Structure

${SKILL_DIR}/
├── SKILL.md                       # This file
├── cpu-rapids-cuda-mapping.tsv    # Index of CPU library → RAPIDS package (TSV)
├── fetch_rapids_apis.py           # Script that (re-)generates apis/<pkg>.txt
└── apis/                          # One API index file per package
    ├── cupy.txt                   # CuPy (replaces numpy)
    ├── cupyx.txt                  # CuPy's SciPy mirror and extensions (replaces scipy)
    ├── cudf.txt                   # cuDF (replaces pandas)
    └── cuml.txt                   # cuML (replaces scikit-learn / umap-learn / hdbscan / statsmodels.tsa)

${SKILL_DIR} is the directory containing this SKILL.md — typically ~/.claude/skills/rapids-first (user-level) or .claude/skills/rapids-first (project-level), with .claude replaced by .agents for Codex. Export it once before the first rg:

SKILL_DIR=$HOME/.claude/skills/rapids-first  # adjust to your install

Standard Workflow

Step 1: Identify the CPU library to replace/select

• Rewrite scenario: scan the user's code to find the imports to accelerate (import numpy as np, import pandas as pd, from sklearn.cluster import KMeans, import scipy.ndimage, from scipy import sparse, import faiss / hnswlib / annoy / umap / hdbscan, etc.).
• New code scenario: against the functional requirements, first mentally write out "if using a CPU library, which one would I use" (pandas? sklearn? scipy?), then follow the steps below to convert it to RAPIDS.

Step 2: Use ripgrep on mapping.tsv to locate the RAPIDS package

cpu-rapids-cuda-mapping.tsv fields:

cpu_module  rapids_target  zero_code  notes

For an exact top-level package lookup use ^pkg\t; for fuzzy submodule lookup use plain grep:

$ rg -P '^pandas\t' "$SKILL_DIR/cpu-rapids-cuda-mapping.tsv"
pandas	cudf	cudf.pandas	zero-code via `python -m cudf.pandas script.py` or first-cell `%load_ext cudf.pandas`; or `import cudf.pandas; cudf.pandas.install()` BEFORE `import pandas`

$ rg -P '^sklearn\.cluster\t' "$SKILL_DIR/cpu-rapids-cuda-mapping.tsv"
sklearn.cluster	cuml.cluster	cuml.accel	accel proxies KMeans, DBSCAN, SpectralClustering; HDBSCAN and AgglomerativeClustering need an explicit cuml.cluster import

$ rg -P '^scipy\.ndimage\t' "$SKILL_DIR/cpu-rapids-cuda-mapping.tsv"
scipy.ndimage	cupyx.scipy.ndimage	-	-

$ rg -P '^sklearn\.neighbors\t' "$SKILL_DIR/cpu-rapids-cuda-mapping.tsv"
sklearn.neighbors	cuml.neighbors	cuml.accel	NearestNeighbors, KNeighborsClassifier, KNeighborsRegressor, KernelDensity

$ rg -i 'faiss' "$SKILL_DIR/cpu-rapids-cuda-mapping.tsv"
faiss	cuml.neighbors.NearestNeighbors	-	exact and IVF search via algorithm='brute'/'ivfflat'/'ivfpq' ('rbc' is limited to <=3 dims); this stack ships no graph index (CAGRA/HNSW)
faiss.Kmeans	cuml.cluster.KMeans	-	GPU k-means with scalable-k-means++ init

Read out rapids_target (target import path) and zero_code (zero-code solution identifier).

Step 3: Check whether the zero-code solution applies

If the zero_code field is not - and the scenario allows it (primarily "rewriting existing CPU code"), prefer the zero-code solution. Canonical activation methods:

Once a zero-code solution is enabled, the original code does not need any import changes; unsupported APIs automatically fall back to CPU without raising errors.

cuml.accel proxies a fixed estimator list: sklearn.cluster KMeans / DBSCAN / SpectralClustering, sklearn.covariance EmpiricalCovariance / LedoitWolf, sklearn.decomposition PCA / IncrementalPCA / TruncatedSVD, sklearn.ensemble RandomForestClassifier / RandomForestRegressor, sklearn.kernel_ridge KernelRidge, sklearn.linear_model LinearRegression / LogisticRegression / Ridge / Lasso / ElasticNet, sklearn.manifold TSNE / SpectralEmbedding, sklearn.neighbors NearestNeighbors / KNeighborsClassifier / KNeighborsRegressor / KernelDensity, sklearn.preprocessing StandardScaler / MinMaxScaler / MaxAbsScaler / LabelEncoder / LabelBinarizer / PolynomialFeatures / TargetEncoder, sklearn.svm SVC / SVR / LinearSVC / LinearSVR, umap.UMAP, and hdbscan.HDBSCAN when the standalone hdbscan package is installed. sklearn.compose, sklearn.pipeline and sklearn.utils are patched for interoperability rather than proxied. Anything outside that list silently stays on CPU — sklearn.naive_bayes, sklearn.metrics, sklearn.feature_extraction, sklearn.random_projection, sklearn.model_selection and sklearn.multiclass have explicit cuml counterparts but no zero-code path, so reach them through an explicit import (Step 4).

Applicability decision:

• Rewrite scenario + user wants "to make existing code run faster" → zero-code
• New code / user wants explicit GPU APIs / user wants the code to clearly read as using RAPIDS → proceed to the explicit import in Step 4

Step 4: Explicit import replacement (when zero-code does not apply, or when writing new code)

Two-step API location:

1. Get rapids_target from mapping.tsv. Examples: numpy → cupy, scipy.ndimage → cupyx.scipy.ndimage, sklearn.cluster → cuml.cluster, faiss → cuml.neighbors.NearestNeighbors.

2. Search for the target API in ${SKILL_DIR}/apis/<pkg>.txt using ripgrep. The four shipped index files are cupy.txt, cupyx.txt, cudf.txt and cuml.txt:

   # Search for a class: exact match of class name followed by ( or .
   rg -i '\.KMeans\('              "$SKILL_DIR/apis/cuml.txt"
   rg -i '^cuml\.cluster\.KMeans'  "$SKILL_DIR/apis/cuml.txt"
   
   # Search for a function: similarly match .funcname(
   rg -i '\.gaussian_filter\('     "$SKILL_DIR/apis/cupyx.txt"
   rg -i '\.read_parquet\('        "$SKILL_DIR/apis/cudf.txt"
   rg -i '\.fft2\('                "$SKILL_DIR/apis/cupy.txt"
   
   # Search for all APIs under a given submodule
   rg '^cuml\.cluster\.'           "$SKILL_DIR/apis/cuml.txt"
   rg '^cupyx\.scipy\.ndimage\.'   "$SKILL_DIR/apis/cupyx.txt"
   
   # Search multiple files at once
   rg -i '\.PCA\('                 "$SKILL_DIR/apis/cuml.txt" "$SKILL_DIR/apis/cupyx.txt"
   

   Each matched line is formatted as "full path(signature) - first line of docstring"; copy the signature directly when writing code.

Step 5: Respect the GPU data lifecycle

• Continuous GPU pipeline: avoid mid-stream round-trips like cudf.DataFrame.to_pandas() → processing → cudf.from_pandas(). If some intermediate step does not yet provide a GPU version, search ${SKILL_DIR}/apis/*.txt once more to confirm before falling back.
• No device mixing: mixing cupy.ndarray with numpy.ndarray, or cudf.DataFrame with pandas.DataFrame, triggers implicit copying and forces stream synchronization. All array types within the same computation graph should be consistent.
• I/O lands directly on GPU: use cudf.read_csv / cudf.read_parquet / cudf.read_orc / cudf.read_json, etc., to go from disk straight to GPU memory, rather than pandas.read_* followed by an upload; the same applies to cuml.preprocessing, which works directly on cuDF.
• cuDF 26.08 tracks pandas 3.0: applymap, backfill, pad, first, last and values_host are gone on both sides, as are the Index.is_boolean / is_categorical / is_floating / is_integer / is_interval / is_numeric dtype predicates. Write map, bfill, ffill and label slicing instead, and reach for cudf.api.types.is_dtype_obj_numeric / is_dtype_obj_string for dtype checks. DataFrame.flags / set_flags and Series.set_flags are new in this release.
• Default dtypes: some cuDF / cuML operators default to float32, while sklearn defaults to float64. For high-precision comparisons, explicitly pass dtype="float64" or convert_dtype=False.
• Fail-fast, no existence checks: importing a RAPIDS package already requires CUDA to be available; do not write defensive fallbacks like try: import cupy except: import numpy as cupy — if the environment is missing, let it fail directly.

Search Examples

Example 1: Accelerate from sklearn.cluster import KMeans to GPU (rewrite scenario)

$ rg -P '^sklearn\.cluster\t' "$SKILL_DIR/cpu-rapids-cuda-mapping.tsv"
sklearn.cluster	cuml.cluster	cuml.accel	accel proxies KMeans, DBSCAN, SpectralClustering; HDBSCAN and AgglomerativeClustering need an explicit cuml.cluster import

• Zero-code preferred: have the user run with python -m cuml.accel script.py; the original code stays untouched.
• Explicit replacement (if the user prefers):

  $ rg -i '^cuml\.cluster\.KMeans\(' "$SKILL_DIR/apis/cuml.txt"
  cuml.cluster.KMeans(*, n_clusters=8, max_iter=300, tol=0.0001, verbose=False, random_state=None, init='scalable-k-means++', n_init='auto', oversampling_factor=2.0, max_samples_per_batch=32768, device_buffer_samples=0, init_size=0, output_type=None) - KMeans is a basic but powerful clustering method which is optimized via
  

  Per the signature, change directly to from cuml.cluster import KMeans. Note the defaults that differ from sklearn: init='scalable-k-means++', and every parameter is keyword-only.

Example 2: Implement a matrix FFT pipeline from scratch (new code scenario)

Requirement: perform fft2 + magnitude + normalization on a batch of 2D matrices.

1. "If using CPU, I would use numpy.fft + numpy" → look up the mapping:

   $ rg -P '^numpy(\.fft)?\t' "$SKILL_DIR/cpu-rapids-cuda-mapping.tsv"
   numpy    cupy    -    import cupy as cp; substitute cp for np
   numpy.fft    cupy.fft    -    -
   

2. Look up the specific API:

   $ rg -i '\.fft2\(' "$SKILL_DIR/apis/cupy.txt"
   cupy.fft.fft2(a, s=None, axes=(-2, -1), norm=None) - Compute the two-dimensional FFT.
   

3. Write the code: a one-shot upload via cp.asarray → cp.fft.fft2 → cp.abs → cp.linalg.norm, all done on GPU, then .get() or write the file output at the very end.

Example 3: Write unit tests for a new algorithm implementation (new test scenario)

Requirement: test that a GPU-implemented PCA produces numerically consistent results with sklearn's PCA.

1. Data generation on GPU — not sklearn.datasets / numpy.random:

   $ rg -i '^cuml\.datasets\.make_blobs\(' "$SKILL_DIR/apis/cuml.txt"
   cuml.datasets.make_blobs(n_samples=100, n_features=2, centers=None, cluster_std=1.0, center_box=(-10.0, 10.0), shuffle=True, random_state=None, return_centers=False, order='F', dtype='float32') - Generate isotropic Gaussian blobs for clustering.
   

   dtype='float32' is the default here, so pass dtype='float64' when the test compares against a float64 sklearn baseline.
2. Run on GPU:

   $ rg -i '^cuml\.decomposition\.PCA\(' "$SKILL_DIR/apis/cuml.txt"
   cuml.decomposition.PCA(*, copy=True, iterated_power=15, n_components=None, svd_solver='auto', tol=1e-07, verbose=False, whiten=False, output_type=None) - PCA (Principal Component Analysis) is a fundamental dimensionality
   

   cuml.decomposition.PCA(n_components=k).fit_transform(X); n_components is keyword-only, unlike sklearn's positional first argument.
3. CPU comparison: one-shot downlink with X.get() → sklearn.decomposition.PCA(...).fit_transform(X_cpu).
4. Assertion:

   $ rg -i '^cupy\.testing\.assert_allclose\(' "$SKILL_DIR/apis/cupy.txt"
   cupy.testing.assert_allclose(actual, desired, rtol=1e-07, atol=0, equal_nan=True, err_msg='', verbose=True, *, strict=False) - Raises an AssertionError if objects are not equal up to desired tolerance.
   

   Compare the absolute values of components, since PCA sign is arbitrary. For dataframe results use cudf.testing.assert_frame_equal.
5. Across the whole process, data transfer happens only once, at step 3.

Example 4: Replace faiss for nearest-neighbor search (rewrite scenario)

$ rg -i 'faiss' "$SKILL_DIR/cpu-rapids-cuda-mapping.tsv"
faiss	cuml.neighbors.NearestNeighbors	-	exact and IVF search via algorithm='brute'/'ivfflat'/'ivfpq' ('rbc' is limited to <=3 dims); this stack ships no graph index (CAGRA/HNSW)
faiss.Kmeans	cuml.cluster.KMeans	-	GPU k-means with scalable-k-means++ init

$ rg -i '^cuml\.neighbors\.NearestNeighbors[(.]' "$SKILL_DIR/apis/cuml.txt"
cuml.neighbors.NearestNeighbors(*, n_neighbors=5, radius=1.0, algorithm='auto', metric='euclidean', p=2, algo_params=None, metric_params=None, n_jobs=None, verbose=False, output_type=None) - NearestNeighbors is an queries neighborhoods from a given set of
cuml.neighbors.NearestNeighbors.as_sklearn(self) - Convert this estimator into an equivalent scikit-learn (or scikit-learn
cuml.neighbors.NearestNeighbors.fit(self, X, y=None, *, convert_dtype='deprecated') -> "'NearestNeighbors'" - NeighborsBase.fit(self, X, y=None, *, convert_dtype='deprecated') -> 'NearestNeighbors'
cuml.neighbors.NearestNeighbors.from_sklearn(model) - Create a cuml estimator from a scikit-learn estimator.
cuml.neighbors.NearestNeighbors.get_params(self, deep=True) - Returns a dict of all params owned by this class. If the child class
cuml.neighbors.NearestNeighbors.kneighbors(self, X=None, n_neighbors=None, return_distance=True, *, convert_dtype='deprecated', two_pass_precision=False) - NeighborsBase.kneighbors(self, X=None, n_neighbors=None, return_distance=True, *, convert_dtype='deprecated', two_pass_precision=False)
cuml.neighbors.NearestNeighbors.kneighbors_graph(self, X=None, n_neighbors=None, mode='connectivity') - NeighborsBase.kneighbors_graph(self, X=None, n_neighbors=None, mode='connectivity')
cuml.neighbors.NearestNeighbors.radius_neighbors_graph(self, X=None, radius=None) - NearestNeighbors.radius_neighbors_graph(self, X=None, radius=None)
cuml.neighbors.NearestNeighbors.set_nvtx_annotations(self)
cuml.neighbors.NearestNeighbors.set_params(self, **params) - Accepts a dict of params and updates the corresponding ones owned by

Rewrite per the signatures: fit(X) ingests the corpus, kneighbors(Q, n_neighbors=k) returns (distances, indices). Pick the index through algorithm: 'brute' for exact search, 'ivfflat' / 'ivfpq' for the approximate IVF variants (tune them via algo_params), 'rbc' for the random ball cover, which only accepts 3 or fewer dimensions. This stack ships no graph index, so a faiss HNSW or a CAGRA index has no direct counterpart — say so and pick the closest IVF configuration instead. faiss.Kmeans maps to cuml.cluster.KMeans.

When RAPIDS Has No Corresponding Implementation

• Know the edges of this stack. It ships cupy, cupyx, cudf and cuml only. Tell the user plainly rather than inventing an API for: graph algorithms (no cugraph, no nx-cugraph backend), image and whole-slide file I/O (no cucim; cupyx.scipy.ndimage covers filtering, morphology, geometric transforms and labelling, but no image decoding or slide readers), ANN graph indexes (no cuvs; cuml.neighbors covers exact and IVF search), multi-GPU or out-of-core dataframes (no dask-cudf), dashboards (no cuxfilter), and GPU forest inference for XGBoost or LightGBM models (cuml.fil / cuml.ForestInference still imports but was deprecated upstream in 26.06, so do not target it in new code).

Otherwise handle by priority:

1. Search for similar keywords again in ${SKILL_DIR}/apis/<pkg>.txt. RAPIDS naming often differs slightly from sklearn / scipy (e.g., sklearn's cross_val_score has no direct counterpart in cuml, but can be reproduced with cuml.model_selection.train_test_split / KFold plus a handwritten loop; sklearn's Pipeline is also absent in cuml but can be chained manually, and cuml.compose.ColumnTransformer covers the column-routing half).
2. Check neighboring packages: an operator missing from cuml or cudf can often be assembled by hand from cupy and cupyx.scipy primitives.
3. When there is still no counterpart, explicitly tell the user that the operator is not in the current RAPIDS stack, then use the CPU version and consolidate data transfers at the CPU↔GPU boundary to minimize the number of transfers (ideal: the entire pipeline does .get() / .to_pandas() only once at the end).

(Re-)Generating apis/

• After any RAPIDS package upgrade, run python "$SKILL_DIR/fetch_rapids_apis.py" to regenerate ${SKILL_DIR}/apis/<pkg>.txt. The script defaults to the four packages this skill covers: cupy, cupyx, cudf, cuml.
• You can also target specific packages only: python "$SKILL_DIR/fetch_rapids_apis.py" --packages cudf cuml.
• The script writes back to ${SKILL_DIR}/apis/ by default (defaults to its own directory), regardless of the current working directory.
• The script must run in "a Python environment with RAPIDS installed" and requires the CUDA driver to be visible.

What Not to Do

• Do not proactively enable cudf.pandas / cuml.accel — monkey-patches affect the entire Python process, so let the user decide whether to turn it on; your job is only to inform them of the activation command.
• Do not write try/except defenses for "is GPU available"; the presence of RAPIDS packages itself assumes CUDA is available — if the environment is missing, let it fail-fast.
• Do not convert every numpy / pandas call to cupy / cudf — in rewrite scenarios, the user may only want to accelerate the hot path; check the context before deciding the scope of refactoring.
• Do not write RAPIDS API signatures from memory; first rg once into ${SKILL_DIR}/apis/<pkg>.txt to get the accurate signature (cuml and sklearn often differ in n_init, output_type, keyword-only parameters, etc.).
• Do not let data downlink mid-stream; place cudf.DataFrame.to_pandas() only at the very end of the pipeline or at necessary integration points (plotting, writing compatible output formats, etc.).
• Do not name a package this stack does not ship (cugraph, nx_cugraph, cucim, cuvs, dask_cudf, cuxfilter); an import that fails is worse than an honest "no GPU path here".