oxicuda_sparse/
lib.rs

1//! # OxiCUDA Sparse -- GPU-Accelerated Sparse Matrix Operations
2//!
3//! This crate provides GPU-accelerated sparse matrix operations,
4//! serving as a pure Rust equivalent to NVIDIA's cuSPARSE library.
5//!
6//! ## Sparse formats
7//!
8//! Multiple storage formats are supported via the [`mod@format`] module:
9//! - [`CsrMatrix`] -- Compressed Sparse Row (primary format)
10//! - [`CscMatrix`] -- Compressed Sparse Column
11//! - [`CooMatrix`] -- Coordinate (triplet)
12//! - [`BsrMatrix`] -- Block Sparse Row
13//! - [`EllMatrix`] -- ELLPACK
14//! - [`HybMatrix`] -- HYB (Hybrid ELL+COO)
15//!
16//! ## Operations
17//!
18//! - [`fn@ops::spmv`] -- Sparse matrix-vector multiply (`y = alpha*A*x + beta*y`)
19//! - [`fn@ops::spmm`] -- Sparse-dense matrix multiply (`C = alpha*A*B + beta*C`)
20//! - [`ops::spgemm`] -- Sparse-sparse matrix multiply (`C = A*B`)
21//! - [`fn@ops::sptrsv`] -- Sparse triangular solve (`L*x = b` or `U*x = b`)
22//! - [`fn@ops::sddmm`] -- Sampled Dense-Dense Matrix Multiply
23//!
24//! ## Preconditioners
25//!
26//! - [`fn@preconditioner::ilu0`] -- Incomplete LU(0) for general systems
27//! - [`fn@preconditioner::ic0`] -- Incomplete Cholesky(0) for SPD systems
28//! - [`fn@preconditioner::ic_k`] -- Incomplete Cholesky with level-of-fill (IC(k))
29//! - [`preconditioner::amg`] -- Smoothed-aggregation algebraic multigrid (setup,
30//!   V-cycle, and a standalone solver)
31//!
32//! ## Eigensolvers
33//!
34//! - [`fn@eig::lobpcg`] -- LOBPCG for the smallest eigenpairs of a sparse SPD
35//!   matrix, with an optional diagonal (Jacobi) preconditioner
36//! - [`fn@eig::shift_invert`] -- shift-invert power iteration for the eigenvalue
37//!   closest to a target shift (interior eigenvalues)
38//!
39//! ## Compatibility shims
40//!
41//! - [`compat::cusparse_compat`] -- a cuSPARSE-flavoured drop-in surface
42//!   (`cusparse_spmv` / `cusparse_spgemm` / `cusparse_spsv`) over the host CSR
43//!   type, for porting cuSPARSE code with minimal churn
44//!
45//! These advanced solvers operate on the host-resident [`host_csr::HostCsr`]
46//! representation, which can be lifted from a [`CsrMatrix`] via
47//! [`HostCsr::from_gpu`](host_csr::HostCsr::from_gpu).
48//!
49//! ## Example
50//!
51//! ```rust,no_run
52//! use oxicuda_sparse::prelude::*;
53//! ```
54
55#![warn(clippy::all)]
56#![warn(missing_docs)]
57
58pub mod compat;
59pub mod eig;
60pub mod error;
61pub mod format;
62pub mod handle;
63pub mod host_csr;
64pub mod ops;
65pub mod preconditioner;
66pub(crate) mod ptx_helpers;
67
68#[cfg(all(test, feature = "gpu-tests"))]
69pub(crate) mod gpu_test_support;
70
71pub use error::{SparseError, SparseResult};
72pub use format::{
73    BsrMatrix, CooMatrix, CscMatrix, Csr5Matrix, CsrMatrix, EllMatrix, HybMatrix, HybPartition,
74    HybStatistics,
75};
76pub use handle::SparseHandle;
77
78/// Prelude for convenient imports.
79pub mod prelude {
80    pub use crate::compat::{
81        CusparseCompatHandle, CusparsePointerMode, cusparse_spgemm, cusparse_spmv, cusparse_spsv,
82    };
83    pub use crate::eig::{LobpcgResult, ShiftInvertResult, lobpcg, shift_invert};
84    pub use crate::error::{SparseError, SparseResult};
85    pub use crate::format::{
86        BsrMatrix, CooMatrix, CscMatrix, Csr5Matrix, CsrMatrix, EllMatrix, HybMatrix, HybPartition,
87        HybStatistics, amd_ordering, inverse_permutation, permute_csr, rcm_ordering,
88    };
89    pub use crate::handle::SparseHandle;
90    pub use crate::host_csr::HostCsr;
91    pub use crate::ops::{
92        BatchScheduler, BatchedSpGEMM, BatchedSpMV, BatchedSpMVPlan, BatchedTriSolve,
93        RecommendedFormat, SpMVAlgo, SpMatFormat, Strategy, UniformBatchedSpMV, analyze_sparsity,
94        auto_spmv, batched_spmv_cpu, csr5_spmv, generate_batched_spmv_ptx,
95        mixed_precision_spmv_cpu, recommend_format, select_format, spgemm_merge, spmm, spmv,
96        spmv_bsr, spmv_ell,
97    };
98    pub use crate::ops::{
99        EdgeFeatures, GnnSparseConfig, MessagePassingOp, add_self_loops, compute_degree_matrix,
100        gather, scatter_reduce, sparse_attention_message, sparse_message_passing,
101        sparse_row_softmax, symmetric_normalize,
102    };
103    pub use crate::ops::{SymbolicPattern, spgemm_symbolic_pattern};
104    pub use crate::preconditioner::{
105        AmgHierarchy, AmgLevel, AmgOptions, IncompleteCholeskyK, amg_setup, amg_solve, amg_v_cycle,
106        ic_k,
107    };
108    pub use crate::preconditioner::{IlukConfig, IlukFactorization};
109}
oxicuda_sparse/lib.rs

oxicuda_sparse/
lib.rs
