Use cuda.ml with tidymodels

Available model specifications

Loading cuda.ml registers the engine name "cuda.ml" for these parsnip specifications:

The SVM engines do not register probability predictions. In particular, predict(fitted_svm, new_data, type = "prob") is not supported. Use logistic_reg(), multinom_reg(), rand_forest(), or nearest_neighbor() when a classification workflow requires probabilities.

Use logistic_reg() for a two-level outcome and multinom_reg() for an outcome with more than two levels. Both specifications call cuda_ml_logistic_reg(); the outcome determines whether cuda.ml uses its binary or multinomial loss.

Set the engine

Set the mode and common arguments in a parsnip specification, then select the cuda.ml engine:

library(cuda.ml)
library(parsnip)

forest_spec <- rand_forest(
  mode = "classification",
  mtry = 2,
  trees = 500,
  min_n = 5
) |>
  set_engine(
    "cuda.ml",
    max_depth = 20,
    n_bins = 256
  )

set.seed(1)
forest_fit <- fit(forest_spec, class ~ ., data = modeldata::hpc_data)

class_predictions <- predict(forest_fit, modeldata::hpc_data, type = "class")
probabilities <- predict(forest_fit, modeldata::hpc_data, type = "prob")

Arguments in the model specification, such as mtry, are common parsnip arguments. Arguments in set_engine(), such as max_depth, are specific to cuda.ml. Put each argument in only one place.

Preprocess with a recipe

cuda.ml’s supervised models require numeric predictors. Scaling is especially important for KNN and SVM models because their fits depend on distances or margins. It is also usually appropriate for penalized linear and logistic models. Fit preprocessing parameters on the training data only, then apply the same recipe to assessment or production data.

This example normalizes the predictors before fitting an exact KNN classifier. A workflow keeps the preprocessing and model specifications together. fit() estimates the recipe from the training data before fitting the cuda.ml model, and predict() applies the recipe to new data before calling the model engine.

library(cuda.ml)
library(parsnip)
library(recipes)
library(workflows)

set.seed(1)
training_rows <- sample(
  seq_len(nrow(modeldata::two_class_dat)),
  floor(0.8 * nrow(modeldata::two_class_dat))
)
training_data <- modeldata::two_class_dat[training_rows, ]
testing_data <- modeldata::two_class_dat[-training_rows, ]

classifier_recipe <- recipe(Class ~ ., data = training_data) |>
  step_normalize(all_numeric_predictors())

knn_spec <- nearest_neighbor(
  mode = "classification",
  neighbors = 5,
  dist_power = 2
) |>
  set_engine(
    "cuda.ml",
    algo = "brute",
    metric = "euclidean"
  )

knn_workflow <- workflow() |>
  add_recipe(classifier_recipe) |>
  add_model(knn_spec)

knn_fit <- fit(knn_workflow, data = training_data)

results <- cbind(
  truth = testing_data$Class,
  predict(knn_fit, testing_data, type = "class"),
  predict(knn_fit, testing_data, type = "prob")
)
head(results)

The parsnip KNN engine defaults to algo = "ivfflat" and metric = "euclidean". ivfflat performs approximate neighbor search. Set algo = "brute", as above, when exact search is required. The direct cuda_ml_knn() interface defaults to brute-force search. The cuda.ml engine does not map parsnip’s weight_func argument; leave it as NULL.

Tree models do not generally need normalization. A recipe can still be useful for creating numeric indicators or applying other preprocessing learned from the training set.

Tune common arguments

cuda.ml registers standard dials parameter metadata for the following parsnip arguments:

These arguments can use tune::tune() in a tuning workflow. margin maps to the epsilon tube and affects SVM regression only; do not tune it for an SVM classifier.

Engine arguments are not registered as dials parameters. Keep them fixed in set_engine() unless you define an explicit dials parameter and range for the tuning workflow. Useful engine arguments include:

Parsnip case weights are not currently supported by the cuda.ml engine. For per-observation weights, use sample_weight with cuda_ml_logistic_reg() or sample_weights with cuda_ml_svm() directly.

Consult the corresponding cuda_ml_*() reference page before setting these arguments. For example, random-forest split criteria differ between classification and regression, and approximate KNN algorithms support fewer distance metrics than brute-force KNN.

Choose between parsnip and the direct API

Use parsnip when you want to compare engines through common specifications, use a tidymodels tuning workflow, or consume standard parsnip prediction types. Parsnip delegates training and prediction to cuda.ml’s public model functions.

The direct API includes several capabilities that have no parsnip specification:

Most algorithm-specific arguments for supported parsnip models remain available through set_engine(). Use the named direct function when selecting the algorithm or solver is part of the analysis, or when passing predictors and outcomes directly is preferable to a parsnip workflow.

For example, cuda.ml’s direct SVM interface supports a "tanh" kernel, but parsnip registration is limited to the RBF, polynomial, and linear SVM specifications.

direct_fit <- cuda_ml_svm(
  Class ~ .,
  data = modeldata::two_class_dat,
  kernel = "tanh",
  cost = 2,
  gamma = 0.1,
  coef0 = 0
)

direct_predictors <- subset(modeldata::two_class_dat, select = -Class)
direct_predictions <- predict(direct_fit, direct_predictors)

See Save and restore models before moving a fitted model to another R process or deployment host.