spacr.gpu_reduce

Build reducers and clusterers on RAPIDS cuML when available, else on the CPU.

Install the optional RAPIDS support with:

pip install spacr[rapids]

No other configuration is required. The CPU path remains the default and is used whenever cuML is absent, the interpreter is unsupported, there is no CUDA device, or the caller has not opted in.

cuML is an optional extra rather than a dependency. cuml-cu12 declares requires_python >= 3.11 with classifiers for 3.11 and 3.12 only, and requires numpy>=2.0 and scipy>=1.14. spaCR supports Python 3.9 through 3.14, so a core dependency would drop four of six interpreters. As an extra it constrains nothing – see the note beside it in setup.py.

cuML implements the algorithms spaCR runs on large tables: UMAP, t-SNE, PCA, DBSCAN and KMeans, and only these are offered here. Other spaCR work – barcode mapping, format conversion, SQLite, report assembly, grouped statistics – is decompression, filesystem and small-table work, where transfer to a GPU costs more time than the computation saves.

Results differ between backends. cuML’s UMAP is not bit-identical to umap-learn’s, and its KMeans and DBSCAN can assign boundary points differently, so a figure regenerated on another machine can change. The accelerator is therefore opt-in per call and reports which backend ran; a 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)	Return the backend, 'cuml' or 'cpu', that method will run on.
describe(→ str)	One line for a log or an About box: what is available, and why not.
install_command(→ List[str])	Return the pip command, as an argument list, that installs the extra.
install_offer()	The same offer install_plan() describes, in the shared shape.
install_plan(→ Dict[str, Any])	Decide what the GPU button should do, without installing anything.
make_reducer(→ Tuple[Any, str])	Build the estimator for method, on whichever backend is available.
python_supported(→ bool)	Whether cuML supports the running Python version (3.11 or 3.12).
rapids_available(→ bool)	Whether cuML is importable and at least one CUDA device is present.

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

Return the backend, 'cuml' or 'cpu', that method will run on.

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]

Return the pip command, as an argument list, that installs the extra.

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]

Decide what the GPU button should do, without installing anything.

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.

This function only reports; the caller performs the installation, which needs a confirmation and a progress bar. Keeping the two separate allows the plan to be queried without side effects.

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

Whether cuML supports the running Python version (3.11 or 3.12).

spacr.gpu_reduce.rapids_available() → bool

Whether cuML is importable and at least one CUDA device is present.

Both are checked because cuML can import on a machine with no GPU and then fail at fit time. Returns False when ENV_FLAG disables RAPIDS.