Crate baracuda_cusparse

Expand description

Safe Rust wrappers for NVIDIA cuSPARSE.

Covers the modern generic-API surface: Handle, SpMat (CSR/CSC/COO/BSR), DnMat, DnVec, and the family of op algorithms — SpMV, SpMM, SpGEMM, SpSV, SpSM, SDDMM — plus CSR↔CSC and sparse↔dense conversions, and the sparse BLAS-1 helpers (axpby, gather, scatter, rot).

All matrix/vector descriptors borrow the underlying DeviceBuffers and tie their lifetime to them so the buffers can’t be freed while cuSPARSE is still holding references.

§Examples

SpMV (sparse-times-dense vector): y = A · x for a 4×4 CSR matrix with 6 non-zeros.

use baracuda_cusparse::{spmv, spmv_buffer_size, DnVec, Handle, Op, SpMVAlg, SpMat};
use baracuda_driver::{Context, Device, DeviceBuffer};

baracuda_driver::init()?;
let device = Device::get(0)?;
let ctx = Context::new(&device)?;
let handle = Handle::new()?;

// A = [[1, 0, 0, 2], [0, 3, 0, 0], [0, 0, 0, 4], [5, 0, 6, 0]], nnz = 6
let mut row_offsets = DeviceBuffer::from_slice(&ctx, &[0i32, 2, 3, 4, 6])?;
let mut col_indices = DeviceBuffer::from_slice(&ctx, &[0i32, 3, 1, 3, 0, 2])?;
let mut values     = DeviceBuffer::from_slice(&ctx, &[1.0f32, 2.0, 3.0, 4.0, 5.0, 6.0])?;
let mut x          = DeviceBuffer::from_slice(&ctx, &[1.0f32, 2.0, 3.0, 4.0])?;
let mut y: DeviceBuffer<f32> = DeviceBuffer::zeros(&ctx, 4)?;

let a = SpMat::csr(4, 4, 6, &mut row_offsets, &mut col_indices, &mut values)?;
let x_d = DnVec::new(&mut x)?;
let mut y_d = DnVec::new(&mut y)?;

let bytes = spmv_buffer_size::<f32>(
    &handle, Op::N, &1.0, &a, &x_d, &0.0, &y_d, SpMVAlg::Default)?;
let mut workspace: DeviceBuffer<u8> = DeviceBuffer::new(&ctx, bytes.max(1))?;
spmv::<f32>(&handle, Op::N, &1.0, &a, &x_d, &0.0, &mut y_d, SpMVAlg::Default, &mut workspace)?;

COO descriptor build — feed an unsorted (row, col, value) triple stream into cuSPARSE without pre-converting to CSR:

use baracuda_cusparse::SpMat;
use baracuda_driver::{Context, Device, DeviceBuffer};

baracuda_driver::init()?;
let device = Device::get(0)?;
let ctx = Context::new(&device)?;

// Same 4×4 matrix as above, expressed as (row, col, value) triples.
let mut row_idx = DeviceBuffer::from_slice(&ctx, &[0i32, 0, 1, 2, 3, 3])?;
let mut col_idx = DeviceBuffer::from_slice(&ctx, &[0i32, 3, 1, 3, 0, 2])?;
let mut values  = DeviceBuffer::from_slice(&ctx, &[1.0f32, 2.0, 3.0, 4.0, 5.0, 6.0])?;

let _coo = SpMat::coo(4, 4, 6, &mut row_idx, &mut col_idx, &mut values)?;
// Pass `_coo` to `spmv`, `spmm`, or `sparse_to_dense` just like a CSR descriptor.

SpMM (sparse-times-dense matrix): C = A · B where A is sparse, B and C are dense column-major.

use baracuda_cusparse::{spmm, spmm_buffer_size, DnMat, Handle, Op, Order, SpMMAlg, SpMat};
use baracuda_driver::{Context, Device, DeviceBuffer};

baracuda_driver::init()?;
let device = Device::get(0)?;
let ctx = Context::new(&device)?;
let handle = Handle::new()?;

// 4×4 CSR A (same as the SpMV example) times a 4×2 dense B → 4×2 dense C.
let mut row_offsets = DeviceBuffer::from_slice(&ctx, &[0i32, 2, 3, 4, 6])?;
let mut col_indices = DeviceBuffer::from_slice(&ctx, &[0i32, 3, 1, 3, 0, 2])?;
let mut values     = DeviceBuffer::from_slice(&ctx, &[1.0f32, 2.0, 3.0, 4.0, 5.0, 6.0])?;
let mut b_data: DeviceBuffer<f32> = DeviceBuffer::zeros(&ctx, 4 * 2)?;
let mut c_data: DeviceBuffer<f32> = DeviceBuffer::zeros(&ctx, 4 * 2)?;

let a = SpMat::csr(4, 4, 6, &mut row_offsets, &mut col_indices, &mut values)?;
let b = DnMat::new(4, 2, /* ld */ 4, Order::Col, &mut b_data)?;
let mut c = DnMat::new(4, 2, /* ld */ 4, Order::Col, &mut c_data)?;

let bytes = spmm_buffer_size::<f32>(
    &handle, Op::N, Op::N, &1.0, &a, &b, &0.0, &c, SpMMAlg::Default)?;
let mut workspace: DeviceBuffer<u8> = DeviceBuffer::new(&ctx, bytes.max(1))?;
spmm::<f32>(&handle, Op::N, Op::N, &1.0, &a, &b, &0.0, &mut c, SpMMAlg::Default,
    &mut workspace)?;

Structs§

DnMat: Dense matrix descriptor for cuSPARSE’s generic API.
DnVec: Dense vector descriptor for cuSPARSE’s generic API.
Handle: Owned cuSPARSE handle.
SpGEMMPlan: Per-plan handle for a 3-phase SpGEMM computation.
SpMat: A sparse-matrix descriptor (CSR / CSC / COO / BSR). The descriptor keeps pointers to externally-owned device buffers; the lifetime parameter ties those buffers to the descriptor.
SpSMPlan: Per-plan handle for an SpSM (sparse triangular solve, multiple RHS).
SpSVPlan: Per-plan handle for an SpSV (sparse triangular solve, single RHS).

Enums§

Csr2CscAlg: Algorithm selector for CSR-to-CSC conversion.
Diag: Unit-diagonal flag for triangular sparse matrices.
Fill: Triangular storage mode for sparse matrices.
IndexBase: Zero- vs one-based indexing for sparse-matrix index arrays.
Op: Transpose / conjugate-transpose selector.
Order: Dense-matrix storage order.
SDDMMAlg: Algorithm selector for cusparseSDDMM.
SpGEMMAlg: Algorithm selector for cusparseSpGEMM.
SpMMAlg: Algorithm selector for cusparseSpMM.
SpMVAlg: Algorithm selector for cusparseSpMV.
SpSMAlg: Algorithm selector for cusparseSpSM.
SpSVAlg: Algorithm selector for cusparseSpSV.

Traits§

SparseScalar: Types that cuSPARSE’s generic API accepts as element / compute type.

Functions§

axpby: Sparse AXPBY: y = alpha * x + beta * y over dense vectors (cusparseAxpby).
csr2csc_ex2: Convert a CSR matrix to CSC format using the modern Ex2 entry point — supports algorithm selection (alg) and arbitrary value types.
csr2csc_ex2_buffer_size: Workspace size in bytes for csr2csc_ex2.
dense_to_sparse_analysis: Run the dense → sparse analysis phase (cusparseDenseToSparse_analysis); fills in the sparsity pattern.
dense_to_sparse_buffer_size: Query buffer-size for a dense → sparse conversion (cusparseDenseToSparse_bufferSize).
dense_to_sparse_convert: Execute the dense → sparse conversion (cusparseDenseToSparse_convert); fills in the sparse values.
gather: Sparse gather: x = y[indices] (cusparseGather).
rot: Givens rotation applied to a pair of sparse/dense vectors (cusparseRot).
scatter: Sparse scatter: y[indices] = x (cusparseScatter).
sddmm: Sampled dense-dense matrix multiply (cusparseSDDMM): computes C = alpha * op(A) * op(B) + beta * C at the sparsity pattern of C.
sddmm_buffer_size: Query buffer-size for the sampled dense-dense matmul (cusparseSDDMM_bufferSize).
sddmm_preprocess: One-time preprocessing before sddmm. See spmm_preprocess for the rationale.
sparse_to_dense: Convert a sparse matrix into a dense one (cusparseSparseToDense).
sparse_to_dense_buffer_size: Query buffer-size for a sparse → dense conversion (cusparseSparseToDense_bufferSize).
spgemm_compute^⚠: Phase 2: compute. Same two-step pattern for buffer2.
spgemm_copy: Phase 3: write output arrays into the pre-populated output SpMat.
spgemm_work_estimation^⚠: Phase 1: work-estimation. The caller provides buffer1 whose size is returned in size1; pass null the first time, then allocate & re-call.
spmm: C = alpha * op(A) * op(B) + beta * C with A sparse, B/C dense (cusparseSpMM).
spmm_buffer_size: Query buffer-size for C = alpha * op(A) * op(B) + beta * C, A sparse.
spmm_preprocess: One-time preprocessing before spmm. Pre-computes algorithm-specific state into workspace so subsequent spmm calls (with the same A sparsity pattern + dimensions) are faster. Use this when the same matrix is multiplied many times.
spmv: y = alpha * op(A) * x + beta * y.
spmv_buffer_size: Query buffer-size for y = alpha * op(A) * x + beta * y.
spsm_analysis: Run the SpSM analysis phase (cusparseSpSM_analysis) — must be called once before spsm_solve.
spsm_buffer_size: Query buffer-size for a multi-RHS sparse triangular solve (cusparseSpSM_bufferSize).
spsm_solve: Execute the multi-RHS sparse triangular solve op(A) * C = alpha * op(B) (cusparseSpSM_solve).
spsv_analysis: Run the SpSV analysis phase (cusparseSpSV_analysis) — must be called once before spsv_solve.
spsv_buffer_size: Query buffer-size for a sparse triangular solve (cusparseSpSV_bufferSize).
spsv_solve: Execute the sparse triangular solve op(A) * y = alpha * x (cusparseSpSV_solve). Requires a prior spsv_analysis call.

Type Aliases§

CsrMatrix: Legacy alias kept for callers from v0.1 — prefer SpMat::csr.
DenseVector: Legacy alias — prefer DnVec.
Error: Error type for cuSPARSE operations.
Result: Result alias.