Remove legacy sparse functionality

[matthewdouglas]

Summary

Removes the sparse matrix multiplication (spmm_coo, spmm_coo_very_sparse) feature and all supporting infrastructure. No downstream library (Transformers, PEFT, Accelerate, TGI, vLLM) uses these functions, and GitHub code search finds zero independent callers outside of forks of this repo.

Removes the cusparse (CUDA) and hipsparse (ROCm) library dependencies entirely.

What was removed

CUDA/HIP kernels (csrc/kernels.cu, csrc/kernels.hip):

• kspmm_coo_very_sparse_naive<T, SPMM_ITEMS, BITS> kernel + 6 explicit template instantiations
• DENORM, MAX_SPARSE_COUNT, SMEM_SIZE macros

Kernel headers (csrc/kernels.cuh, csrc/kernels_hip.cuh):

• kspmm_coo_very_sparse_naive declaration

Ops-level launchers (csrc/ops.cu, csrc/ops.hip):

• spmm_coo() (cusparse/hipsparse SpMM wrapper)
• spmm_coo_very_sparse_naive<T, BITS>() + template instantiations

Op headers (csrc/ops.cuh, csrc/ops_hip.cuh):

• #include <cusparse.h> / #include <hipsparse/hipsparse.h>
• CHECK_CUSPARSE / CHECK_HIPSPARSE error-checking macros
• ContextCusparse / ContextHipsparse handle wrapper classes
• spmm_coo and spmm_coo_very_sparse_naive declarations

Python interface (csrc/pythonInterface.cpp):

• get_cusparse() factory function
• cspmm_coo()
• cspmm_coo_very_sparse_naive_fp16() / _int8()
• HIP compatibility #defines for ContextCusparse and cusparseHandle_t

Python API (bitsandbytes/functional.py):

• COOSparseTensor, CSRSparseTensor, CSCSparseTensor
• coo_zeros(), coo2csr(), coo2csc()
• spmm_coo(), spmm_coo_very_sparse()
• Cusparse_Context singleton

Library loader (bitsandbytes/cextension.py):

• lib.get_cusparse.restype registration

Build system (CMakeLists.txt):

• CUDA::cusparse link target
• find_package(hipsparse REQUIRED) + roc::hipsparse link target

Tests (tests/test_functional.py):

• TestSpMMFunctional class (test_spmm_coo, test_spmm_bench, test_spmm_coo_very_sparse, test_spmm_coo_dequant)
• TestSparseTensorFunctional class (test_coo2csr, test_coo2csc)

CI (.github/workflows/):

• Removed cusparse and cusparse_dev from CUDA sub-packages in both test-runner.yml and python-package.yml

Agent guide updates

• agents/api_surface.md: removed section 4.9 (Sparse Operations), Cusparse_Context singleton entry, and Tier 4 list entries; renumbered subsequent sections
• agents/architecture_guide.md: removed cusparse/hipsparse from build dependency table
• agents/code_standards.md: removed CHECK_CUSPARSE from error-checking examples and Cusparse_Context from singleton list
• agents/issue_patterns.md: updated "Missing libcusparse" issue pattern to generic shared-library mismatch (bitsandbytes no longer links cusparse)

[github-actions]

The docs for this PR live here. All of your documentation changes will be reflected on that endpoint. The docs are available until 30 days after the last update.

[matthewdouglas]

PR Review: #1881 — Remove legacy sparse functionality

Removes spmm_coo, spmm_coo_very_sparse, all COO/CSR/CSC sparse tensor types, Cusparse_Context, and the cusparse/hipsparse library dependencies. The PR description's claim that no downstream library uses these functions is verified — grep across Transformers, PEFT, Accelerate, TGI, and vLLM integration points in agents/downstream_integrations.md shows zero references.

No blocking issues.

What was checked:

• Python caller verification: grep across the entire Python tree confirms zero remaining references to all removed symbols (spmm_coo, COOSparseTensor, CSRSparseTensor, CSCSparseTensor, Cusparse_Context, coo_zeros, coo2csr, coo2csc). ✓

• C/CUDA/HIP sweep: grep across csrc/ and CMakeLists.txt confirms zero remaining references to cusparse, hipsparse, ContextCusparse, ContextHipsparse, get_cusparse, or cspmm*. ✓

• CUDA/HIP symmetry: Both backends receive identical removals (kernel, launcher, header, Python interface). ✓

• Build system: CUDA::cusparse removed from target_link_libraries in CUDA path; find_package_and_print_version(hipsparse REQUIRED) and roc::hipsparse removed from HIP path. CMake change is correct and minimal. ✓

• CI workflow: cusparse and cusparse_dev removed from sub-packages in both python-package.yml and test-runner.yml. Correct. ✓

• Test import cleanup: The removed sparse test classes were the only users of HIP_ENVIRONMENT in test_functional.py. The import was correctly narrowed to ROCM_WARP_SIZE_64 only. ✓

• Comment fix in cuda/ops.py: The stale "COO tensor" comment at bitsandbytes/backends/cuda/ops.py:174 is updated to accurately describe what the function does. Minor but correct.

• Agent docs: api_surface.md (section 4.9 removed + 4.10–4.13 renumbered, Cusparse_Context singleton removed, Tier 4 list updated), architecture_guide.md (dependency table), code_standards.md (singleton list + error-checking macro example), and issue_patterns.md (libcusparse error pattern generalized) are all consistently updated. ✓

• Downstream impact: The sparse API was not used by any downstream integration (Transformers, PEFT, Accelerate, TGI, vLLM). ✓

• Security: Clear (internal author, removes a dependency — reduces attack surface)

• Downstream impact: None (no downstream consumers of sparse API)

• Tests: Adequate (sparse test classes removed with the code; remaining suite passes)

• CI: All pass (CUDA, ROCm, CPU, XPU, Windows)

• Serialization: Not affected

• torch.compile: Not affected