.ggmlr_umap_gpu: GPU-bound UMAP embedding (op = "umap")

Description

Lays a feature-by-cell matrix out in 2-D with UMAP. The kNN graph uses the FNN kd-tree when available (exact, O(n log n), light on memory); without FNN it falls back to a full distance matrix, computed on the GPU via the pairwise_dist.comp shader (honest f32, sidestepping mul_mat's f16 path) or on the CPU. The SGD layout optimisation runs on the GPU via umap_sgd.comp under backend = "vulkan" (the default), falling back to its exact CPU reference when the GPU is unavailable. The fuzzy simplicial set in between stays on the CPU (sparse). backend_dist in the metadata reports the kNN path actually taken ("fnn", "vulkan", or "cpu").

Usage

.ggmlr_umap_gpu(
  mat,
  n_components = 2L,
  n_neighbors = 15L,
  min_dist = 0.1,
  spread = 1,
  n_epochs = 200L,
  gpu_neighbor_max_cells = NULL,
  backend = c("vulkan", "cpu"),
  sgd_backend = c("cpu", "vulkan"),
  knn_backend = c("cpu", "vulkan")
)

Value

A ggml_result whose embedding is cells x

n_components. metadata records the a/b curve parameters and the per-phase backend (backend_dist, backend_sgd); the summary

backend is "vulkan" only when both phases ran on the GPU.

Arguments

mat: Dense numeric matrix, features x cells.
n_components: Output dimensionality (UMAP is virtually always 2).
n_neighbors: kNN graph size (default 15).
min_dist: Minimum spacing of points in the embedding (default 0.1).
spread: Scale of the embedding (default 1).
n_epochs: SGD epochs (default 200).
gpu_neighbor_max_cells: Cell ceiling for the GPU distance shader. NULL (default) derives it from free VRAM; a positive integer forces an explicit cap; above the ceiling the distance phase falls back to the CPU.
backend: "vulkan" (default; GPU for the kNN/distance phase, with per-phase CPU fallback) or "cpu" (force the CPU reference for both phases).
sgd_backend: Which backend runs the SGD layout phase: "cpu" (default, the single-threaded reference — best embedding quality) or "vulkan" (the GPU shader — faster but lower quality on dense graphs, as its Hogwild SGD does not match the reference; falls back to CPU if no GPU is live). The graph/distance phase is unaffected and still uses backend.