Skip to content

Commit 071c85d

Browse files
Intron7Intron7
committed
add blogpost
1 parent 06fd387 commit 071c85d

1 file changed

Lines changed: 175 additions & 0 deletions

File tree

‎content/blog/2026-rsc-goes-nanobind.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# rapids-singlecell 0.15.0: Prebuilt CUDA Wheels and Compiled Kernels
2+
3+
*rapids-singlecell 0.15.0 now ships GPU kernels as precompiled extensions instead of being compiled at runtime. Here's what that means for you.*
4+
5+
---
6+
7+
## Why the packaging changed
8+
9+
In earlier versions of rapids-singlecell, all GPU kernels were written as CuPy RawKernels. These were compiled the first time you called them — in your environment, on your machine. That worked, but it came with friction:
10+
11+
- **First-call latency.** The initial invocation of a kernel-backed function could take several seconds while nvrtc compiled the CUDA source.
12+
- **Silent dtype/layout mismatches.** A RawKernel receives raw pointers. If the input array had the wrong dtype or wasn't C-contiguous, the kernel might silently produce garbage rather than raising an error.
13+
- **CUDA code trapped in Python strings.** RawKernels are defined as CUDA source inside Python string literals. That means no syntax highlighting, no autocomplete, and no compiler warnings in your editor — debugging C++ code buried in a Python string is nobody's idea of a good time.
14+
15+
Starting with 0.15.0, these kernels are compiled once at build time and shipped as nanobind/CUDA C++ extension modules inside the wheel. The result is a more conventional compiled-extension workflow: you `pip install` the package and every kernel is ready immediately.
16+
17+
## What changed
18+
19+
The GPU kernels that were previously CuPy RawKernels are now nanobind C++ extensions built with `scikit-build-core` and CMake. This gives us:
20+
21+
- **No runtime compilation** for any migrated kernel — the compiled code is in the wheel.
22+
- **Typed bindings at the Python/C++ boundary.** nanobind enforces dtype (e.g. float32 vs float64) and memory layout (C-contiguous vs F-contiguous) before the kernel launches, so mismatches raise a clear `TypeError` instead of producing wrong results.
23+
- **A conventional C++/CUDA project structure** with headers, shared helpers, and room for larger fused or fully C++ GPU routines. Harmony2, shipping in this release, is the first example of a more complex function built on this foundation.
24+
- **CUDA-versioned wheel packaging.** CI builds separate wheels for each CUDA major version — `rapids-singlecell-cu12` and `rapids-singlecell-cu13` — each with a `[rapids]` dependency extra that pulls in the matching RAPIDS and CuPy packages.
25+
26+
The Python API and import name are unchanged:
27+
28+
```python
29+
import rapids_singlecell as rsc
30+
```
31+
32+
Your existing analysis scripts should work without modification.
33+
34+
## CUDA-specific wheels
35+
36+
Because the kernels are now compiled binaries, we need to ship one wheel per CUDA major version. (Python wheel tags don't encode CUDA version, so we encode it in the package name — the same approach used by CuPy, PyTorch, and other CUDA-dependent packages.)
37+
38+
| Package name | Compiled with | Runtime CUDA support | Blackwell GPUs |
39+
|---|---|---|---|
40+
| `rapids-singlecell-cu12` | CUDA 12.2 | CUDA 12.2 – 12.9+ | Via PTX JIT (sm_90) |
41+
| `rapids-singlecell-cu13` | CUDA 13.0 | CUDA 13.0+ | Native binaries |
42+
43+
Both wheels are available for **x86_64** and **aarch64** on Linux.
44+
45+
If you have a Blackwell GPU (B200, GB200) and want the best out-of-the-box performance, the CUDA 13 wheel includes native binaries for Blackwell architectures. The CUDA 12 wheel still supports Blackwell through PTX just-in-time compilation, so it will work, but the first kernel launch on Blackwell will be slightly slower while the driver JIT-compiles the PTX.
46+
47+
## How to install
48+
49+
### Prebuilt wheel (recommended)
50+
51+
Pick the wheel that matches your CUDA version:
52+
53+
```bash
54+
pip install rapids-singlecell-cu13 # CUDA 13
55+
pip install rapids-singlecell-cu12 # CUDA 12
56+
```
57+
58+
This installs rapids-singlecell with precompiled kernels, but does **not** pull in the RAPIDS stack (cupy, cuml, cudf, etc.). If you manage those dependencies separately — for example, through conda — this is all you need.
59+
60+
### Prebuilt wheel with RAPIDS dependencies
61+
62+
If you want pip to also install the matching RAPIDS and CuPy packages:
63+
64+
```bash
65+
pip install 'rapids-singlecell-cu13[rapids]' --extra-index-url=https://pypi.nvidia.com
66+
pip install 'rapids-singlecell-cu12[rapids]' --extra-index-url=https://pypi.nvidia.com
67+
```
68+
69+
Note: on the prebuilt wheels, the dependency extra is always `[rapids]`. The CUDA version is determined by which package name you install — `rapids-singlecell-cu12` or `rapids-singlecell-cu13`. If you're building from source instead, the extras are `[rapids-cu12]` and `[rapids-cu13]`.
70+
71+
### Conda / Mamba
72+
73+
Environment files are provided in the repository:
74+
75+
```bash
76+
conda env create -f conda/rsc_rapids_26.04_cuda13.yml # Python 3.14, CUDA 13
77+
conda env create -f conda/rsc_rapids_26.04_cuda12.yml # Python 3.14, CUDA 12
78+
```
79+
80+
> **Note:** RAPIDS currently does not support `channel_priority: strict`. Use `channel_priority: flexible` instead.
81+
82+
### Docker / Apptainer
83+
84+
Pre-built containers are available for both CUDA versions:
85+
86+
```bash
87+
docker pull ghcr.io/scverse/rapids-singlecell-cu13:latest
88+
docker run --rm --gpus all ghcr.io/scverse/rapids-singlecell-cu13:latest
89+
```
90+
91+
For HPC clusters using Apptainer/Singularity:
92+
93+
```bash
94+
apptainer pull rsc.sif docker://ghcr.io/scverse/rapids-singlecell-cu13:latest
95+
apptainer run --nv rsc.sif
96+
```
97+
98+
## Migration from 0.14.x
99+
100+
For most users, upgrading is straightforward:
101+
102+
1. **Change your pip install command.** Replace `pip install rapids-singlecell` with `pip install rapids-singlecell-cu12` or `rapids-singlecell-cu13`, depending on your CUDA version.
103+
2. **No code changes needed.** The `import rapids_singlecell as rsc` import and all public APIs remain the same.
104+
3. **Check your CUDA version.** Run `nvidia-smi` or `nvcc --version` to confirm whether you're on CUDA 12.x or CUDA 13.x, and install the matching wheel. If you're using conda, make sure the CUDA runtime library version in your environment matches the wheel you install — e.g., `cuda-cudart` from the `nvidia` channel should be 12.x for the cu12 wheel or 13.x for the cu13 wheel.
105+
106+
## What about `pip install rapids-singlecell`?
107+
108+
The plain install — `pip install rapids-singlecell`, without the `-cu12` or `-cu13` suffix — still works. It will compile the CUDA extensions from source during installation. This is perfectly functional, but please be aware of what that means: you need a CUDA toolkit with nvcc, CMake ≥ 3.24, and a compatible C++ compiler already present in your environment, and the build will take longer than downloading a prebuilt wheel.
109+
110+
When building from source, you can install the matching RAPIDS dependencies with the `[rapids-cu12]` or `[rapids-cu13]` extra:
111+
112+
```bash
113+
pip install 'rapids-singlecell[rapids-cu12]' --extra-index-url=https://pypi.nvidia.com
114+
```
115+
116+
Or install the RAPIDS stack separately before or after the build.
117+
118+
For most users, we recommend the prebuilt CUDA wheels. They're faster to install and don't require a local compiler toolchain. For more details on source builds — including how to target custom GPU architectures — see the [installation docs](https://rapids-singlecell.readthedocs.io/en/latest/installation.html).
119+
120+
Source builds are the right choice if you are:
121+
122+
- **Contributing to rapids-singlecell** and need to iterate on C++ kernel code.
123+
- **Debugging CUDA extensions** and want to compile with debug flags or sanitizers.
124+
- **Targeting a custom GPU architecture** not covered by the prebuilt wheels (e.g. a future compute capability).
125+
- **On a platform we don't publish wheels for** (though we cover x86_64 and aarch64 Linux).
126+
127+
If none of those apply to you, use the prebuilt wheel.
128+
129+
## Other highlights in 0.15.0
130+
131+
Beyond packaging, this release includes a substantial set of algorithmic and performance improvements built up across the 0.15.0 development cycle:
132+
133+
### Harmony2 and C++ harmony
134+
135+
Harmony was rewritten as a C++ nanobind kernel ([#578](https://github.com/scverse/rapids-singlecell/pull/578)), making it significantly faster and more memory-efficient. On top of that, we implemented three algorithmic improvements from the Harmony2 paper (Patikas et al. 2026): a stabilized diversity penalty, dynamic per-cluster-per-batch ridge regularization, and automatic batch pruning to prevent overintegration in biologically heterogeneous datasets ([#625](https://github.com/scverse/rapids-singlecell/pull/625)). This is also the first example of a more complex routine built on the new compiled-kernel infrastructure.
136+
137+
### Contrast-based energy distance
138+
139+
Perturbation experiments typically don't need a full k×k distance matrix between all groups — you want to compare each perturbation against one or two controls, possibly stratified by cell type. The new `contrast_distances()` API ([#603](https://github.com/scverse/rapids-singlecell/pull/603)) lets you express exactly that. You build a contrasts DataFrame — either with the `Distance.create_contrasts()` helper or by hand — where each row is a (target, reference) comparison, optionally stratified by `split_by` columns (e.g., cell type). Under the hood, the kernel deduplicates shared distance pairs across contrasts, subsets the embedding to only the referenced cells before transferring to GPU, and launches a single kernel call for all unique pairs. The result is a copy of your contrasts DataFrame with an `edistance` column appended.
140+
141+
```python
142+
from rapids_singlecell.pertpy_gpu import Distance
143+
144+
dist = Distance("edistance")
145+
146+
# Compare each perturbation against two controls, stratified by cell type
147+
contrasts = Distance.create_contrasts(
148+
adata,
149+
groupby="target_gene",
150+
selected_group=["Non_target", "Scramble"],
151+
split_by="cell_type",
152+
)
153+
154+
result = dist.contrast_distances(adata, contrasts=contrasts)
155+
```
156+
157+
`onesided_distances()` also now accepts a sequence of control group names via `selected_group`, returning a DataFrame with one column per control ([#601](https://github.com/scverse/rapids-singlecell/pull/601)). Both energy distance and co-occurrence kernels gained multi-GPU support ([#545](https://github.com/scverse/rapids-singlecell/pull/545), [#546](https://github.com/scverse/rapids-singlecell/pull/546)).
158+
159+
### More highlights
160+
161+
- **Dask support for `highly_variable_genes`** with the Seurat v3 flavor ([#616](https://github.com/scverse/rapids-singlecell/pull/616)).
162+
- **CUDA kernel error surfacing** — launch errors are now raised instead of silently continuing ([#619](https://github.com/scverse/rapids-singlecell/pull/619)).
163+
- **RAPIDS 26.04 and Python 3.14 support** across all CI and conda environments.
164+
165+
## Get started
166+
167+
```bash
168+
pip install rapids-singlecell-cu13 # or rapids-singlecell-cu12
169+
```
170+
171+
For questions and bug reports, visit the [GitHub issue tracker](https://github.com/scverse/rapids_singlecell/issues).
172+
173+
---
174+
175+
*rapids-singlecell is part of the [scverse](https://scverse.org) ecosystem. If you use it in your research, please cite the project.*

0 commit comments

Comments
 (0)