Metadata-Version: 2.5
Name: cuspa
Version: 0.1.0rc1
Summary: GPU spatial operations for spatial-omics workloads.
Project-URL: Homepage, https://github.com/NVIDIA/cuspa
Project-URL: Documentation, https://nvidia.github.io/cuspa/
Project-URL: Issues, https://github.com/NVIDIA/cuspa/issues
Project-URL: Repository, https://github.com/NVIDIA/cuspa
Author: NVIDIA Corporation
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: GPU :: NVIDIA CUDA
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.12
Requires-Dist: numpy>=1.23
Provides-Extra: docs
Requires-Dist: hatch-vcs>=0.5; extra == 'docs'
Requires-Dist: hatchling; extra == 'docs'
Requires-Dist: myst-parser>=2; extra == 'docs'
Requires-Dist: numpydoc>=1.8; extra == 'docs'
Requires-Dist: nvidia-sphinx-theme==0.0.9.post1; extra == 'docs'
Requires-Dist: pydata-sphinx-theme<0.17,>=0.16; extra == 'docs'
Requires-Dist: sphinx-copybutton; extra == 'docs'
Requires-Dist: sphinx-design; extra == 'docs'
Requires-Dist: sphinx>=8.1; extra == 'docs'
Provides-Extra: geoarrow
Requires-Dist: pyarrow>=14; extra == 'geoarrow'
Provides-Extra: geopandas
Requires-Dist: geopandas>=1.0; extra == 'geopandas'
Requires-Dist: pyarrow>=14; extra == 'geopandas'
Provides-Extra: spatialdata
Requires-Dist: geopandas>=1.0; extra == 'spatialdata'
Requires-Dist: pyarrow>=14; extra == 'spatialdata'
Requires-Dist: shapely>=2.0; extra == 'spatialdata'
Requires-Dist: spatialdata>=0.2; extra == 'spatialdata'
Provides-Extra: test
Requires-Dist: pytest-timeout>=2.3; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Requires-Dist: scipy>=1.13; extra == 'test'
Description-Content-Type: text/markdown

# cuspa: GPU spatial operations for spatial omics

[![CI](https://github.com/NVIDIA/cuspa/actions/workflows/ci.yml/badge.svg)](https://github.com/NVIDIA/cuspa/actions/workflows/ci.yml)

cuspa assigns transcript coordinates to cell polygons and builds sparse
cells-by-genes count matrices on the GPU. Geometry is stored in flat
GeoArrow-style buffers. GeoPandas and SpatialData inputs are converted before
GPU computation.

## Installation

Install the prebuilt wheel for your CUDA major version:

```bash
[uv] pip install cuspa-cu12  # CUDA 12
[uv] pip install cuspa-cu13  # CUDA 13
```

Both distributions provide the `cuspa` Python package; install only one per
environment. The optional adapters are extras, for example
`[uv] pip install "cuspa-cu12[geopandas]"`; `geoarrow` and `spatialdata` work
the same way.

cuspa requires Python 3.12 or newer, a compatible NVIDIA GPU and driver, a CUDA
12 or CUDA 13 runtime, and CuPy or CUDA-enabled PyTorch. Install the CuPy or
PyTorch package for your CUDA environment separately. Aggregation and I/O
adapters currently require CuPy.

To build from source instead, install the `cuspa` source distribution. This
requires the matching CUDA toolkit and a C++17 compiler:

```bash
[uv] pip install cuspa
```

See the [installation guide](https://nvidia.github.io/cuspa/install.html) for
wheel targets and source-build details.

## Usage

```python
import cuspa as cs

polys = cs.io.from_spatialdata(sdata, "cell_boundaries")
tx = cs.io.transcripts_from_spatialdata(sdata, "transcripts")

csr = cs.tl.aggregate_to_cells(
    [(tx.xy, tx.gene_ids)],
    polys,
    num_genes=len(tx.gene_names),
)
```

## Documentation

See the [documentation](https://nvidia.github.io/cuspa/) for installation,
usage, geometry input, and the API reference.

## Contributing

External contributions are open through pull requests. Report bugs and propose
changes through [GitHub Issues](https://github.com/NVIDIA/cuspa/issues/new/choose).
See [CONTRIBUTING.md](CONTRIBUTING.md) for the contribution process. All project
participants must follow the [Code of Conduct](CODE_OF_CONDUCT.md).

## Security

Do not report vulnerabilities through public GitHub issues. See
[SECURITY.md](SECURITY.md) for NVIDIA's private reporting channels.

## License

cuspa is licensed under Apache-2.0. See [LICENSE](LICENSE).
