.ggmlr_neighbors_gpu: kNN + shared-nearest-neighbour graphs (op = "neighbors")

Description

Builds the two neighbour graphs that Seurat's FindNeighbors produces: a binary kNN graph and a shared-nearest-neighbour (SNN) graph whose edge weights are the Jaccard overlap of the two endpoints' neighbourhoods. The kNN search uses the FNN kd-tree when available, otherwise the pairwise distance matrix (GPU pairwise_dist.comp or CPU). The SNN step is sparse matrix arithmetic. Matches Seurat numerically: SNN weight = |N(i) cap N(j)| / |N(i) cup N(j)| with the neighbour set including the point itself, pruned below prune_snn.

Usage

.ggmlr_neighbors_gpu(
  mat,
  n_neighbors = 20L,
  prune_snn = 1/15,
  gpu_neighbor_max_cells = NULL,
  backend = c("vulkan", "cpu"),
  knn_backend = c("cpu", "vulkan")
)

Value

A ggml_result with metadata$kind = "graph" and the two graphs (nn, snn) as sparse matrices in

metadata; embedding is the SNN graph (the one clustering uses).

Arguments

mat: Dense numeric matrix, features x cells (e.g. PC coordinates).
n_neighbors: kNN graph size (Seurat default 20).
prune_snn: Drop SNN edges with Jaccard below this (Seurat default 1/15).
gpu_neighbor_max_cells: Cell ceiling for the GPU distance fallback; NULL derives it from free VRAM.
backend: "vulkan" or "cpu" (dispatch resolves "auto").
knn_backend: Which backend runs the kNN search: "cpu" (default, the FNN kd-tree) or "vulkan" to opt into the fused GPU kNN (knn_tiled.comp, honest f32, no n x n matrix). The GPU path is for large n, where the kd-tree degrades in ~10-D; it falls back to the CPU if the GPU is unavailable, n_neighbors > 32, or n exceeds the VRAM ceiling. Only takes effect under backend = "vulkan".