Get started with cuda.ml

cuda.ml provides R interfaces to GPU-accelerated machine learning algorithms from RAPIDS cuML. This guide installs the managed runtime, checks its status, fits a regression model, and computes a principal-component representation.

The examples are not evaluated when this vignette is built. Building the vignette therefore does not require a GPU, a native backend, network access, or a runtime download.

Check the system requirements

Native cuda.ml operations require Linux x86_64 with glibc 2.28 or newer. The GPU workflows in this guide also require a supported NVIDIA GPU and an NVIDIA driver version 580 or newer. On Windows, install and run R inside a compatible WSL2 Linux distribution; native Windows R is not supported. macOS, Linux ARM64, musl-based Linux distributions, and older glibc versions are not supported.

CPU-only nvForest inference has separate requirements and does not require an NVIDIA GPU or driver. See nvForest inference and deployment for that path.

Install cuda.ml and its runtime

Install the R package from CRAN, then explicitly provision the complete GPU backend:

install.packages("cuda.ml")

library(cuda.ml)
cuda_ml_install()

Installing the R package does not install or load CUDA, RAPIDS, or the native cuda.ml backend. cuda_ml_install() downloads and verifies the backend and its locked runtime libraries. A repeated call with the same inputs reuses the completed cache.

For cache configuration, mirrors, source builds, runtime audits, and cleanup, see Install and manage cuda.ml.

Inspect the backend

Use cuda_ml_backend_info() to inspect the backend selected for this R installation and whether its exact managed cache is complete:

info <- cuda_ml_backend_info()

info[c(
  "package_version",
  "platform",
  "cuda_version",
  "rapids_version",
  "minimum_driver",
  "runtime_installed"
)]

This check is read-only. It does not access the network, inspect an NVIDIA GPU or driver, or load native code. In particular, runtime_installed = TRUE means the expected cache is complete; it is not a GPU-readiness check.

Fit and predict with a direct model API

Supervised model functions accept familiar formula and data-frame inputs. This ordinary least-squares example holds out the final seven rows of mtcars, fits the model on the remaining rows, and predicts the held-out outcomes:

train <- mtcars[1:25, ]
test <- mtcars[26:32, ]

fit <- cuda_ml_ols(
  mpg ~ .,
  data = train,
  method = "qr"
)

test_predictors <- subset(test, select = -mpg)
predictions <- predict(fit, new_data = test_predictors)

cbind(
  actual = test$mpg,
  predicted = predictions$.pred
)

The fitted model retains the preprocessing blueprint learned from the formula. predict() applies that blueprint to new_data before sending the resulting numeric predictors to the backend.

Compute a lower-dimensional representation

Unsupervised and transformation functions take observations in rows and numeric features in columns. Because the measurements below have different ranges, the example scales them before calling cuda_ml_pca(). The function mean-centers the scaled features, fits the principal components, and, by default, transforms the input data:

oils <- modeldata::oils
oil_predictors <- oils |>
  subset(select = -class) |>
  scale()

pca_fit <- cuda_ml_pca(
  oil_predictors,
  n_components = 2
)

head(pca_fit$transformed_data)
pca_fit$explained_variance_ratio

The rows of transformed_data correspond to the input rows, and its columns are the retained components. The fitted object also contains the component matrix, feature means, singular values, explained variance, and explained variance ratios.

Understand returned values

cuda.ml follows these output conventions:

Regression predictions are data frames with a .pred column.
Class predictions are data frames with a factor column named .pred_class.
Class-probability predictions have one .pred_<level> column per outcome level when the model supports probability prediction.
Unsupervised and transformation functions return model-specific objects. Consult the function reference for their named components; for example, PCA stores the fitted-input representation in transformed_data, while k-means stores assignments in labels and centers in centroids.

These prediction column names are compatible with tidymodels conventions. Most native backend inputs are converted to numeric matrices after formula, recipe, or data-frame preprocessing. Consult each function’s reference page for its accepted input forms and output components.

Choose the direct API or parsnip

Use cuda.ml’s direct functions when you need an unsupervised or transformation algorithm, want algorithm-specific controls, or do not need a tidymodels workflow. Use the optional parsnip engines when cuda.ml should participate in a tidymodels workflow with consistent model specifications, preprocessing, resampling, or tuning. Install parsnip separately for that interface.

See Use cuda.ml with tidymodels for supported specifications, modes, and engine arguments.

Continue

Install and manage cuda.ml covers deployment, configuration, source builds, audits, and cleanup.
Use cuda.ml with tidymodels covers parsnip and recipe workflows.
Save and restore models compares the available persistence formats.
nvForest inference and deployment covers GPU training, external tree ensembles, and CPU or GPU inference.