GPU SpMV

Focused CUDA sparse matrix-vector multiplication library

CSR + ELL formats · 4 kernels · explicit errors · minimal maintenance surface

English · 简体中文

What it is

GPU SpMV is a C++17 / CUDA library for sparse matrix-vector multiplication on NVIDIA GPUs. The repository now concentrates on the core library only:

• Storage: CSR and ELL sparse formats
• Execution: Scalar CSR, Vector CSR, Merge Path, and ELL kernels
• Engineering: CudaBuffer<T> RAII, explicit SpMVError, CPU reference paths, focused tests

Non-core showcase modules and AI governance layers have been removed to keep the codebase smaller and easier to maintain.

Quick start

git clone https://github.com/AICL-Lab/gpu-spmv.git
cd gpu-spmv

cmake --preset cuda-linux
cmake --build --preset cuda-linux
ctest --preset cuda-linux

CPU-only environments can use:

cmake -S . -B build-no-cuda -DSPMV_REQUIRE_CUDA=OFF
cmake --build build-no-cuda
ctest --test-dir build-no-cuda --output-on-failure

On Linux, GPU builds now have first-class presets that pin the system GCC/G++ host toolchain and avoid Conda compiler leakage:

cmake --preset cuda-linux
cmake --build --preset cuda-linux
ctest --preset cuda-linux

For release builds:

cmake --preset cuda-linux-release
cmake --build --preset cuda-linux-release
ctest --preset cuda-linux-release

Minimal example

#include <spmv/csr_matrix.h>
#include <spmv/cuda_buffer.h>
#include <spmv/spmv.h>

int main() {
    float dense[] = {
        1.0f, 0.0f, 2.0f,
        0.0f, 3.0f, 4.0f,
        0.0f, 0.0f, 5.0f,
    };

    spmv::CSRMatrix* csr = spmv::csr_create(3, 3, 5);
    spmv::csr_from_dense(csr, dense, 3, 3);
    spmv::csr_to_gpu(csr);

    spmv::CudaBuffer<float> d_x(3);
    spmv::CudaBuffer<float> d_y(3);
    const float h_x[] = {1.0f, 1.0f, 1.0f};
    cudaMemcpy(d_x.data(), h_x, sizeof(h_x), cudaMemcpyHostToDevice);

    spmv::SpMVConfig config = spmv::spmv_auto_config(csr);
    spmv::SpMVResult result = spmv::spmv_csr(csr, d_x.data(), d_y.data(), &config, 3);
    spmv::csr_destroy(csr);

    return result.error_code == 0 ? 0 : 1;
}

Project layout

gpu-spmv/
├── include/spmv/   # Public headers
├── src/            # Core library implementation
├── tests/          # Unit and regression tests
├── docs/           # GitHub Pages site
├── CHANGELOG.md    # Single project changelog
└── CMakeLists.txt

Documentation

Documentation is published at https://aicl-lab.github.io/gpu-spmv/.

Page	Purpose
Quick Start	Installation and build flow
API Reference	Core public API
Architecture	Data flow and kernel selection
Performance Guide	Practical tuning notes
Examples	End-to-end usage

Version history is kept only in the root CHANGELOG.md.

Contributing

Keep changes boring and verifiable:

1. Make the smallest change that improves the core library.
2. Preserve RAII resource handling; do not introduce raw cudaMalloc / cudaFree.
3. Run the existing build and test commands.
4. Update the relevant documentation when behavior changes.

See CONTRIBUTING.md for the short contribution workflow.

License

MIT License. See LICENSE.