Skip to content

Store indices as uint16 when the minor axis fits in 2**16 - #101

Open
aarmey wants to merge 1 commit into
mainfrom
uint16-indices
Open

aarmey wants to merge 1 commit into
mainfrom
uint16-indices

Conversation

@aarmey

@aarmey aarmey commented Nov 17, 2026

Copy link
Copy Markdown
Member

What

smallest_index_dtype(n) now returns uint16 for axes up to 65,536 long and keeps int32/int64 beyond that. The narrowing already happens in the array constructor (_base.py), so every path that builds an array (from_scipy, load_packed, ops, selections) picks it up. Files written with an older indices_dtype attribute are narrowed on read.

Why

For single-cell data the minor axis is the gene axis (typically 20k to 60k), and int32 indices spend 4 B/nnz where 2 B suffice. The CUDA path already narrows to uint16 on device (_index_dtype in _cuda.py); this makes the host arrays match.

Measurements

Lupus (1.01B nnz, 32,738 genes), load_packed:

  • indices in memory: 4.04 GB (int32) to 2.02 GB (uint16)
  • Numba VCSR SpMV (y = A @ x), best of 5:
indices 48 threads 1 thread
int32 91.8 ms 1.05 s
uint16 53.6 ms 0.91 s

Output was identical. SpMV on one dataset and one machine, so treat the speedup as indicative.

Tests

  • tests/test_index_dtypes.py: updated the narrowing assertions from int32 to uint16; boundary test now covers 1, 216, 216 + 1, int32 max, and int32 max + 1; added a test that index n_minor - 1 round-trips on both sides of 2**16 for CSR and CSC.
  • Full suite: 1,906 passed, 73 skipped; tests/test_cuda.py 371 passed on an RTX 4090; ruff check and ruff format --check clean.

Review notes

  • uint16 is unsigned, so any code doing signed arithmetic on indices (for example indices - k) could wrap. The existing suite, including the property tests, found none, but I only searched by running the tests, not by auditing every kernel.
  • Axes between 65,537 and 2**31 stay int32, so behaviour there is unchanged.

smallest_index_dtype now returns uint16 for axes up to 2**16, falling back to
int32/int64 beyond that. For a gene axis this halves the bytes of indices in
memory (4 -> 2 B/nnz); the CUDA path already narrowed to uint16 on device.

Measured on lupus (1.01B nnz, 32,738 genes), numba VCSR SpMV, 48 threads:
int32 91.8 ms -> uint16 53.6 ms (1 thread: 1.05 s -> 0.91 s).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant