oxicuda-sparse 0.4.0

OxiCUDA Sparse - GPU-accelerated sparse matrix operations (cuSPARSE equivalent)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106

//! # OxiCUDA Sparse -- GPU-Accelerated Sparse Matrix Operations
//!
//! This crate provides GPU-accelerated sparse matrix operations,
//! serving as a pure Rust equivalent to NVIDIA's cuSPARSE library.
//!
//! ## Sparse formats
//!
//! Multiple storage formats are supported via the [`mod@format`] module:
//! - [`CsrMatrix`] -- Compressed Sparse Row (primary format)
//! - [`CscMatrix`] -- Compressed Sparse Column
//! - [`CooMatrix`] -- Coordinate (triplet)
//! - [`BsrMatrix`] -- Block Sparse Row
//! - [`EllMatrix`] -- ELLPACK
//! - [`HybMatrix`] -- HYB (Hybrid ELL+COO)
//!
//! ## Operations
//!
//! - [`fn@ops::spmv`] -- Sparse matrix-vector multiply (`y = alpha*A*x + beta*y`)
//! - [`fn@ops::spmm`] -- Sparse-dense matrix multiply (`C = alpha*A*B + beta*C`)
//! - [`ops::spgemm`] -- Sparse-sparse matrix multiply (`C = A*B`)
//! - [`fn@ops::sptrsv`] -- Sparse triangular solve (`L*x = b` or `U*x = b`)
//! - [`fn@ops::sddmm`] -- Sampled Dense-Dense Matrix Multiply
//!
//! ## Preconditioners
//!
//! - [`fn@preconditioner::ilu0`] -- Incomplete LU(0) for general systems
//! - [`fn@preconditioner::ic0`] -- Incomplete Cholesky(0) for SPD systems
//! - [`fn@preconditioner::ic_k`] -- Incomplete Cholesky with level-of-fill (IC(k))
//! - [`preconditioner::amg`] -- Smoothed-aggregation algebraic multigrid (setup,
//!   V-cycle, and a standalone solver)
//!
//! ## Eigensolvers
//!
//! - [`fn@eig::lobpcg`] -- LOBPCG for the smallest eigenpairs of a sparse SPD
//!   matrix, with an optional diagonal (Jacobi) preconditioner
//! - [`fn@eig::shift_invert`] -- shift-invert power iteration for the eigenvalue
//!   closest to a target shift (interior eigenvalues)
//!
//! ## Compatibility shims
//!
//! - [`compat::cusparse_compat`] -- a cuSPARSE-flavoured drop-in surface
//!   (`cusparse_spmv` / `cusparse_spgemm` / `cusparse_spsv`) over the host CSR
//!   type, for porting cuSPARSE code with minimal churn
//!
//! These advanced solvers operate on the host-resident [`host_csr::HostCsr`]
//! representation, which can be lifted from a [`CsrMatrix`] via
//! [`HostCsr::from_gpu`](host_csr::HostCsr::from_gpu).
//!
//! ## Example
//!
//! ```rust,no_run
//! use oxicuda_sparse::prelude::*;
//! ```

#![warn(clippy::all)]
#![warn(missing_docs)]

pub mod compat;
pub mod eig;
pub mod error;
pub mod format;
pub mod handle;
pub mod host_csr;
pub mod ops;
pub mod preconditioner;
pub(crate) mod ptx_helpers;

pub use error::{SparseError, SparseResult};
pub use format::{
    BsrMatrix, CooMatrix, CscMatrix, Csr5Matrix, CsrMatrix, EllMatrix, HybMatrix, HybPartition,
    HybStatistics,
};
pub use handle::SparseHandle;

/// Prelude for convenient imports.
pub mod prelude {
    pub use crate::compat::{
        CusparseCompatHandle, CusparsePointerMode, cusparse_spgemm, cusparse_spmv, cusparse_spsv,
    };
    pub use crate::eig::{LobpcgResult, ShiftInvertResult, lobpcg, shift_invert};
    pub use crate::error::{SparseError, SparseResult};
    pub use crate::format::{
        BsrMatrix, CooMatrix, CscMatrix, Csr5Matrix, CsrMatrix, EllMatrix, HybMatrix, HybPartition,
        HybStatistics, amd_ordering, inverse_permutation, permute_csr, rcm_ordering,
    };
    pub use crate::handle::SparseHandle;
    pub use crate::host_csr::HostCsr;
    pub use crate::ops::{
        BatchScheduler, BatchedSpGEMM, BatchedSpMV, BatchedSpMVPlan, BatchedTriSolve,
        RecommendedFormat, SpMVAlgo, SpMatFormat, Strategy, UniformBatchedSpMV, analyze_sparsity,
        auto_spmv, batched_spmv_cpu, csr5_spmv, generate_batched_spmv_ptx,
        mixed_precision_spmv_cpu, recommend_format, select_format, spgemm_merge, spmm, spmv,
        spmv_bsr, spmv_ell,
    };
    pub use crate::ops::{
        EdgeFeatures, GnnSparseConfig, MessagePassingOp, add_self_loops, compute_degree_matrix,
        gather, scatter_reduce, sparse_attention_message, sparse_message_passing,
        sparse_row_softmax, symmetric_normalize,
    };
    pub use crate::ops::{SymbolicPattern, spgemm_symbolic_pattern};
    pub use crate::preconditioner::{
        AmgHierarchy, AmgLevel, AmgOptions, IncompleteCholeskyK, amg_setup, amg_solve, amg_v_cycle,
        ic_k,
    };
    pub use crate::preconditioner::{IlukConfig, IlukFactorization};
}