cuML - RAPIDS ML Algorithms

Common errors

• TypeError: Sparse input of type <class 'scipy.sparse.csc.csc_matrix'> is not supported. Please convert your data to cupy.ndarray or cudf.DataFrame.

  cause Passing a `scipy.sparse` matrix to a cuML algorithm that expects a dense array or a different sparse format after strict validation was introduced in v26.04.00.
  fix Convert your sparse input to a dense `cupy.ndarray` or `cudf.DataFrame` using `.toarray()` or similar methods, or ensure it's in a sparse format explicitly supported by the algorithm (if any).

• ModuleNotFoundError: No module named 'dask'

  cause Attempting to import or use functionality from `cuml.dask` (e.g., `cuml.dask.cluster.KMeans`) when Dask is not installed. Dask became an optional dependency in v25.12.00.
  fix Install Dask and Distributed: `pip install dask distributed` or `conda install -c conda-forge dask-ml`.

• AttributeError: 'RandomForestClassifier' object has no attribute 'handle'

  cause Attempting to access the `handle` attribute on a cuML estimator. This attribute was deprecated and removed from public APIs in v26.02.00.
  fix Remove any code directly accessing `estimator.handle`. The `handle` was an internal CUDA context management object not intended for direct user interaction.

• ImportError: cannot import name 'check_is_fitted' from 'cuml.internals' (or similar)

  cause The `check_is_fitted` utility function was moved to `cuml.internals.validation` in v26.04.00.
  fix Update your import statement to `from cuml.internals.validation import check_is_fitted`.

Warnings

• breaking Sparse input validation now raises `TypeError` for unsupported types. Algorithms that previously implicitly handled or failed with unsupported sparse formats will now explicitly raise an error.
  Fix: Ensure sparse inputs are converted to `cudf.SparseSeries`, `cudf.SparseDataFrame`, or a dense `cudf.DataFrame`/`cupy.ndarray` as required by the specific algorithm, or to a sparse format explicitly supported by the algorithm (e.g., `scipy.sparse.csr_matrix` for some estimators).
• breaking The `check_is_fitted` utility function has been moved from `cuml.internals` to `cuml.internals.validation` for better organization and adherence to internal validation structures.
  Fix: Update import statements from `from cuml.internals import check_is_fitted` to `from cuml.internals.validation import check_is_fitted`.
• gotcha `dask` became an optional dependency. Attempting to use `cuml.dask` modules or distributed functionalities without `dask` installed will result in a `ModuleNotFoundError`.
  Fix: If you plan to use distributed cuML algorithms, explicitly install `dask` and `distributed` via `pip install dask distributed` or `conda install dask-ml`.
• deprecated The `TotalIters` parameter for SVC/SVR estimators has been deprecated. It may be removed in future versions.
  Fix: Review your code for usage of `TotalIters` in SVC/SVR. If it's used, consider alternative ways to manage iteration limits or consult the latest documentation for equivalent parameters, if any.
• deprecated The `handle` attribute has been deprecated and removed from public cuML APIs. Direct access to `estimator.handle` is no longer supported.
  Fix: Avoid accessing the `handle` attribute directly. This attribute exposed internal CUDA context management and should not be used by end-users. If explicit CUDA stream or resource management is required, refer to advanced RAPIDS documentation for proper techniques.
• breaking Deprecated `convert_to_*` methods (e.g., `convert_to_cupy`, `convert_to_cudf`) in `cuml.ensemble` estimators have been removed in favor of `as_*` methods (e.g., `as_cupy`, `as_cudf`).
  Fix: Update calls from `estimator.convert_to_cupy()` to `estimator.as_cupy()`, and similarly for `cudf`.

Install

• pip install cuml-cu12 cupy-cuda12x Pip install (requires existing CUDA 12.x environment)
• conda install -c rapidsai -c conda-forge -c nvidia cuml=26.04 python=3.11 cudatoolkit=12.2 Conda install (recommended for easier environment management)

Imports

• KMeans

  from cuml.cluster import KMeans

• LogisticRegression

  from cuml.linear_model import LogisticRegression

• RandomForestClassifier

  from cuml.ensemble import RandomForestClassifier

• check_is_fitted
  wrong:

  from cuml.internals import check_is_fitted

  correct:

  from cuml.internals.validation import check_is_fitted

  Path changed in v26.04.00

Quickstart

This quickstart demonstrates basic GPU-accelerated K-Means clustering using cuML. It generates sample data on the CPU, transfers it to the GPU using CuPy, performs the clustering, and then retrieves the results back to the CPU. Ensure `cupy-cuda12x` is installed alongside `cuml-cu12`.

import cuml
import cupy as cp
import numpy as np

# For reproducibility
np.random.seed(0)

# Generate some random data on the CPU
n_samples = 1000
n_features = 2
n_clusters = 3
X_host = np.random.rand(n_samples, n_features) * 10

# Simulate clusters
for i in range(n_clusters):
    X_host[i*n_samples//n_clusters:(i+1)*n_samples//n_clusters] += i * 2

# Transfer data to GPU using CuPy
X_gpu = cp.asarray(X_host, dtype=cp.float32)

# Initialize and train KMeans on the GPU
kmeans_cuml = cuml.cluster.KMeans(n_clusters=n_clusters, random_state=0)
kmeans_cuml.fit(X_gpu)

# Get cluster centers and labels (still on GPU)
cluster_centers_gpu = kmeans_cuml.cluster_centers_
labels_gpu = kmeans_cuml.labels_

print("CuML KMeans fitted successfully.")
print(f"Cluster Centers (on GPU):\n{cluster_centers_gpu}")
print(f"First 10 Labels (on GPU): {labels_gpu[:10]}")

# Transfer results back to CPU if needed
cluster_centers_cpu = cluster_centers_gpu.get()
labels_cpu = labels_gpu.get()

print(f"Cluster Centers (on CPU):\n{cluster_centers_cpu}")
print(f"First 10 Labels (on CPU): {labels_cpu[:10]}")