spacr.gpu_reduce

RAPIDS cuML where it helps, and the CPU implementation everywhere else.

Install the optional RAPIDS support with:

pip install spacr[rapids]

and nothing else changes. The CPU path stays the default, stays tested, and stays the answer whenever cuML is absent, the interpreter is wrong, there is no CUDA device, or the caller asks for determinism.

WHY AN EXTRA AND NEVER A DEPENDENCY. cuml-cu12 declares requires_python >= 3.11 with classifiers for 3.11 and 3.12 ONLY, and wants numpy>=2.0 and scipy>=1.14. spaCR promises 3.9 through 3.14, so making it core would drop four of six interpreters. As an extra it constrains nothing – see the note beside it in setup.py.

WHERE IT ACTUALLY HELPS. cuML implements the algorithms spaCR already runs on big tables: UMAP, t-SNE, PCA, DBSCAN and KMeans. Those are the ones offered here. Everything else spaCR does – barcode mapping, format conversion, SQLite, report assembly, grouped statistics – is decompression, filesystem and small-table work, and moving it to a GPU would cost transfer time and buy nothing. GPU acceleration is reserved for workloads where transfer overhead is outweighed by computation.

Determinism is a real difference, not a footnote. cuML’s UMAP is not bit-identical to umap-learn’s, and its KMeans and DBSCAN can differ at the boundaries. A figure regenerated on a different machine would move. So the accelerator is OPT-IN per call, reports which backend ran, and any caller that pins a seed for reproducibility should keep the CPU path.

Functions

availability_entry(→ Dict[str, Any])	GPU acceleration as the shared hover panel wants it.
backend_for(→ str)	'cuml' or 'cpu' for method, and never a surprise.
describe(→ str)	One line for a log or an About box: what is available, and why not.
install_command(→ List[str])	The command that installs the extra. Separate so it can be shown.
install_offer()	The same offer install_plan() describes, in the shared shape.
install_plan(→ Dict[str, Any])	What pressing GPU should do, decided before anything is installed.
make_reducer(→ Tuple[Any, str])	Build the estimator for method, on whichever backend is available.
python_supported(→ bool)	Can cuML be installed into the interpreter running this?
rapids_available(→ bool)	Is cuML importable AND is there a device for it?

Module Contents

spacr.gpu_reduce.availability_entry() → Dict[str, Any]

GPU acceleration as the shared hover panel wants it.

Mirrors spacr.regression_backends.availability_entry(), so the panel takes one mapping shape and neither caller imports the other.

Returns:

{key, title, reason, url, offer, enabled}.

spacr.gpu_reduce.backend_for(method: str, *, prefer_gpu: bool = False) → str

'cuml' or 'cpu' for method, and never a surprise.

Parameters:

• method – reducer name. Only algorithms in ACCELERATED can select cuML; unsupported names remain on the CPU path.

• prefer_gpu – opt in. Default False, so an existing caller keeps the CPU path and the reproducibility that goes with it.

Returns:

the backend that will actually run.

spacr.gpu_reduce.describe() → str

One line for a log or an About box: what is available, and why not.

spacr.gpu_reduce.install_command() → List[str]

The command that installs the extra. Separate so it can be shown.

spacr.gpu_reduce.install_offer()

The same offer install_plan() describes, in the shared shape.

The Image UMAP’s GPU acceleration and the regression backend picker ask the same question, so they answer it in the same vocabulary and one hover panel serves both. This is the bridge – install_plan() keeps its own dict because the Hyperparameter screen already reads it.

Returns:

a spacr.updater.InstallOffer, whose action is ready, install, elsewhere or impossible.

spacr.gpu_reduce.install_plan() → Dict[str, Any]

What pressing GPU should do, decided before anything is installed.

Returns:

{action, message}. action is ready when cuML and a device are available; install when this interpreter can install it; wrong_python when another Python version is required; or no_device when installing more cannot provide a CUDA device.

NOTHING IS INSTALLED HERE. This function decides and reports; the caller installs, because installing is the part that needs a confirmation and a progress bar, and a function that did both could not be asked “what would happen” without it happening.

spacr.gpu_reduce.make_reducer(method: str, *, prefer_gpu: bool = False, **kwargs) → Tuple[Any, str]

Build the estimator for method, on whichever backend is available.

Parameters:

• method – reducer name understood by the cuML or CPU estimator factories (umap, tsne, pca, dbscan or kmeans).

• kwargs – passed to the estimator. The parameter names cuML shares with the CPU libraries – n_neighbors, min_dist, n_components, eps, min_samples, n_clusters – carry through unchanged, which is what makes one call site serve both.

Returns:

(estimator, backend). The backend is returned rather than logged only, so a caller can record WHICH one produced a figure.

Raises:

ImportError – the CPU library for method is missing. A missing optional GPU is a fallback; a missing required CPU library is a genuine setup problem and is not silently worked around.

spacr.gpu_reduce.python_supported() → bool

Can cuML be installed into the interpreter running this?

spacr.gpu_reduce.rapids_available() → bool

Is cuML importable AND is there a device for it?

Both halves matter: cuML imports happily on a machine with no GPU and then fails at fit time, which would turn an optional accelerator into a crash on exactly the machines that did not ask for one.