--- title: "Get started with cuda.ml" description: > Install the cuda.ml runtime, inspect the backend, and run supervised and dimensionality-reduction workflows on a GPU. output: rmarkdown::html_vignette vignette: > %\VignetteIndexEntry{Get started with cuda.ml} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} --- ```{r setup, include = FALSE} knitr::opts_chunk$set( collapse = TRUE, comment = "#>", eval = FALSE ) ``` 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](install-manage.html#windows-through-wsl2); 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](nvforest.html) for that path. ## Install cuda.ml and its runtime Install the R package from CRAN, then explicitly provision the complete GPU backend: ```{r install} 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](install-manage.html). ## 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: ```{r backend-info} 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: ```{r supervised} 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: ```{r pca} 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_` 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](tidymodels.html) for supported specifications, modes, and engine arguments. ## Continue - [Install and manage cuda.ml](install-manage.html) covers deployment, configuration, source builds, audits, and cleanup. - [Use cuda.ml with tidymodels](tidymodels.html) covers parsnip and recipe workflows. - [Save and restore models](model-persistence.html) compares the available persistence formats. - [nvForest inference and deployment](nvforest.html) covers GPU training, external tree ensembles, and CPU or GPU inference.