oxiblas_sparse/
lib.rs

1//! OxiBLAS Sparse - Sparse matrix support.
2//!
3//! This crate provides sparse matrix formats and operations:
4//!
5//! - **CSR**: Compressed Sparse Row format
6//! - **CSC**: Compressed Sparse Column format
7//! - **COO**: Coordinate format (for construction)
8//! - **DIA**: Diagonal format (for banded matrices)
9//! - **ELL**: ELLPACK format (for GPU computation)
10//! - **BSR**: Block Sparse Row format (for block-structured matrices)
11//! - **BSC**: Block Sparse Column format (for column-oriented block structure)
12//! - **HYB**: Hybrid ELL+COO format (for irregular sparsity patterns)
13//! - **SELL**: Sliced ELLPACK format (for GPU-optimized row-variable matrices)
14//!
15//! # Sparse Matrix Formats
16//!
17//! ## CSR (Compressed Sparse Row)
18//!
19//! Efficient for row-wise operations and matrix-vector products.
20//! Stores values row by row.
21//!
22//! ## CSC (Compressed Sparse Column)
23//!
24//! Efficient for column-wise operations and direct solvers.
25//! Stores values column by column.
26//!
27//! ## DIA (Diagonal)
28//!
29//! Efficient for banded matrices (tridiagonal, pentadiagonal, etc.).
30//! Stores diagonals explicitly.
31//!
32//! ## ELL (ELLPACK)
33//!
34//! Efficient for GPU computation with uniform row lengths.
35//! Fixed number of entries per row.
36//!
37//! ## BSR (Block Sparse Row)
38//!
39//! Efficient for block-structured matrices (FEM, etc.).
40//! Stores dense blocks in CSR-like structure.
41//!
42//! # Example
43//!
44//! ```
45//! use oxiblas_sparse::{CsrMatrix, CscMatrix, DiaMatrix, EllMatrix, BsrMatrix};
46//!
47//! // Create a sparse matrix in CSR format
48//! // [1 0 2]
49//! // [0 3 0]
50//! // [4 0 5]
51//! let values = vec![1.0, 2.0, 3.0, 4.0, 5.0];
52//! let col_indices = vec![0, 2, 1, 0, 2];
53//! let row_ptrs = vec![0, 2, 3, 5];
54//!
55//! let csr = CsrMatrix::new(3, 3, row_ptrs, col_indices, values).unwrap();
56//! assert_eq!(csr.nnz(), 5);
57//!
58//! // Convert to CSC
59//! let csc = csr.to_csc();
60//! assert_eq!(csc.nnz(), 5);
61//!
62//! // Create a tridiagonal matrix in DIA format
63//! let sub = vec![1.0, 1.0];
64//! let main = vec![2.0, 2.0, 2.0];
65//! let super_diag = vec![1.0, 1.0];
66//! let dia = DiaMatrix::tridiagonal(sub, main, super_diag).unwrap();
67//! assert_eq!(dia.ndiag(), 3);
68//! ```
69
70#![warn(missing_docs)]
71#![warn(clippy::all)]
72#![allow(clippy::module_name_repetitions)]
73// Sparse library uses Clone::clone() for generic T where Copy isn't always available
74#![allow(clippy::clone_on_copy)]
75// Manual assign patterns are often clearer in numerical code
76#![allow(clippy::assign_op_pattern)]
77// Numerical code often has complex generic types for performance
78#![allow(clippy::type_complexity)]
79// Loop index variables are common in matrix operations
80#![allow(clippy::needless_range_loop)]
81// Sparse functions have many parameters by design
82#![allow(clippy::too_many_arguments)]
83// Partial ordering comparisons are intentional
84#![allow(clippy::neg_cmp_op_on_partial_ord)]
85// Bounds in two places for clarity in generic numerical code
86#![allow(clippy::multiple_bound_locations)]
87// Manual slice copying for explicit control
88#![allow(clippy::manual_memcpy)]
89// Vec vs slice in internal APIs is acceptable
90#![allow(clippy::ptr_arg)]
91// Iterative solver implementations may have unusual control flow
92#![allow(clippy::never_loop)]
93#![allow(clippy::collapsible_if)]
94#![allow(clippy::iter_cloned_collect)]
95#![allow(clippy::only_used_in_recursion)]
96#![allow(clippy::manual_strip)]
97#![allow(clippy::doc_overindented_list_items)]
98#![allow(clippy::unnecessary_unwrap)]
99
100pub mod bsc;
101pub mod bsr;
102pub mod convert;
103pub mod coo;
104pub mod csc;
105pub mod csr;
106pub mod dia;
107pub mod ell;
108pub mod graph;
109pub mod hyb;
110pub mod linalg;
111pub mod mtx;
112pub mod ops;
113pub mod sell;
114pub mod stochastic;
115pub mod test_matrices;
116
117pub use bsc::{BscError, BscMatrix};
118pub use bsr::{BsrError, BsrMatrix, DenseBlock};
119pub use convert::{
120    RecommendedFormat,
121    SparsityAnalysis,
122    // Analysis utilities
123    analyze_sparsity_pattern,
124    // New format conversions
125    bsc_to_bsr,
126    bsc_to_csr,
127    bsr_to_bsc,
128    // Core conversions
129    bsr_to_csr,
130    bsr_to_dia,
131    bsr_to_ell,
132    coo_to_csc,
133    coo_to_csr,
134    csc_to_coo,
135    csc_to_csr,
136    csr_to_bsc,
137    csr_to_bsr,
138    csr_to_coo,
139    csr_to_csc,
140    csr_to_dia,
141    csr_to_ell,
142    csr_to_hyb,
143    csr_to_sell,
144    dia_to_bsr,
145    dia_to_csr,
146    dia_to_ell,
147    ell_to_bsr,
148    ell_to_csr,
149    ell_to_dia,
150    ell_to_hyb,
151    hyb_to_csr,
152    hyb_to_ell,
153    sell_to_csr,
154};
155pub use coo::{CooMatrix, CooMatrixBuilder};
156pub use csc::CscMatrix;
157pub use csr::CsrMatrix;
158pub use dia::{DiaError, DiaMatrix};
159pub use ell::{EllError, EllMatrix};
160pub use graph::{
161    BandwidthProfileResult, BipartiteMatchingResult, BipartiteResult, ConnectedComponentsResult,
162    LevelSetResult, PartitionResult, WeightedMatchingResult, bandwidth_profile,
163    bandwidth_profile_csc, bipartite_matching, connected_components, connected_components_csc,
164    degree_sequence, is_bipartite, is_structurally_symmetric, level_sets, partition_graph_bisect,
165    partition_graph_kway, pseudo_peripheral_vertex, weighted_bipartite_matching,
166};
167pub use hyb::{HybError, HybMatrix, HybStats, HybWidthStrategy};
168pub use mtx::{
169    MtxError, MtxField, MtxFormat, MtxHeader, MtxObject, MtxSymmetry, read_matrix_market,
170    read_matrix_market_coo, read_matrix_market_str, write_matrix_market, write_matrix_market_str,
171    write_matrix_market_symmetric,
172};
173pub use sell::{SellError, SellMatrix, SellStats, SliceSize};
174pub use stochastic::{
175    DiagEstimate, ProbeType, StochasticConfig, StochasticError, StochasticEstimator, TraceEstimate,
176};
177pub use test_matrices::{
178    TestMatrixError, arrow_matrix, diagonal, laplacian_2d, laplacian_3d, poisson_1d, random_spd,
179    tridiagonal,
180};
181
182/// Prelude module for convenient imports.
183pub mod prelude {
184    pub use crate::bsc::BscMatrix;
185    pub use crate::bsr::{BsrMatrix, DenseBlock};
186    pub use crate::coo::{CooMatrix, CooMatrixBuilder};
187    pub use crate::csc::CscMatrix;
188    pub use crate::csr::CsrMatrix;
189    pub use crate::dia::DiaMatrix;
190    pub use crate::ell::EllMatrix;
191    pub use crate::graph::{
192        BandwidthProfileResult, BipartiteMatchingResult, BipartiteResult,
193        ConnectedComponentsResult, LevelSetResult, PartitionResult, WeightedMatchingResult,
194        bandwidth_profile, bipartite_matching, connected_components, degree_sequence, is_bipartite,
195        is_structurally_symmetric, level_sets, partition_graph_bisect, partition_graph_kway,
196        pseudo_peripheral_vertex, weighted_bipartite_matching,
197    };
198    pub use crate::hyb::{HybMatrix, HybWidthStrategy};
199    pub use crate::linalg::prelude::*;
200    pub use crate::ops::{spmm, spmm_sparse, spmv};
201    pub use crate::sell::{SellMatrix, SliceSize};
202}
oxiblas_sparse/lib.rs

oxiblas_sparse/
lib.rs
