Quick Start

This guide will help you install GPU SpMV and run your first program in 5 minutes.

System Requirements

Component	Minimum	Recommended
CUDA Toolkit	11.0	12.0+
CMake	3.18	3.25+
C++ Compiler	GCC 7+ / MSVC 2019+	GCC 11+ / MSVC 2022+
NVIDIA GPU	CC 7.0 (Volta)	CC 8.6+ (Ampere)
GPU Memory	4 GB	8 GB+

Verify CUDA Installation

nvcc --version
nvidia-smi

Installation

1. Clone Repository

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

2. Build

Using CMake Presets (recommended on Linux):

# Debug build for development and tests
cmake --preset cuda-linux
cmake --build --preset cuda-linux

# Release build
cmake --preset cuda-linux-release
cmake --build --preset cuda-linux-release

Or using traditional method:

cmake -S . -B build-cuda-release \
  -DCMAKE_BUILD_TYPE=Release \
  -DCMAKE_C_COMPILER=/usr/bin/gcc \
  -DCMAKE_CXX_COMPILER=/usr/bin/g++ \
  -DCMAKE_CUDA_HOST_COMPILER=/usr/bin/g++
cmake --build build-cuda-release

3. Run Tests

# Run all tests
ctest --preset cuda-linux

# Or run test binary directly
./build-cuda/spmv_tests

Your First Program

Create first_spmv.cpp:

#include <spmv/spmv.h>
#include <cstdio>

int main() {
    // Create 3x3 sparse matrix: [1 0 2; 0 3 4; 0 0 5]
    float dense[] = {1, 0, 2, 0, 3, 4, 0, 0, 5};

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

    // Prepare input vector x = [1, 1, 1]
    float h_x[] = {1, 1, 1};
    CudaBuffer<float> d_x(3), d_y(3);
    cudaMemcpy(d_x.data(), h_x, 3 * sizeof(float), cudaMemcpyHostToDevice);

    // Execute SpMV: y = A * x
    SpMVConfig config = spmv_auto_config(csr);
    SpMVResult result = spmv_csr(csr, d_x.data(), d_y.data(), &config, 3);

    if (result.error == SpMVError::SUCCESS) {
        printf("Success! Time: %.3f ms\n", result.time_ms);

        // Read result
        float h_y[3];
        cudaMemcpy(h_y, d_y.data(), 3 * sizeof(float), cudaMemcpyDeviceToHost);
        printf("Result: [%.0f, %.0f, %.0f]\n", h_y[0], h_y[1], h_y[2]);
        // Output: [3, 7, 5]
    }

    csr_destroy(csr);
    return 0;
}

Compile and Run

# Compile
nvcc -o first_spmv first_spmv.cpp \
    -I./include \
    -L./build-cuda-release -lgpu_spmv \
    -lcudart

# Run
./first_spmv

Troubleshooting

CUDA Not Found?

Ensure CUDA is properly installed and environment variables are set:

export PATH=/usr/local/cuda/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH

Tests Failing?

Check if GPU is available:

nvidia-smi

If your shell injects Conda compilers, use the Linux CUDA presets instead of the generic presets:

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

For CPU-only testing:

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

Next Steps

• API Reference - Complete interface documentation
• Examples - More usage examples
• Performance - Optimization guide