algebra_sparse/
lib.rs

1// Copyright (C) 2020-2025 algebra-sparse authors. All Rights Reserved.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! # algebra-sparse
16//!
17//! A sparse linear algebra library built on top of [nalgebra], providing efficient sparse matrix
18//! and vector operations.
19//!
20//! ## Features
21//!
22//! - **Compressed Sparse Matrix Storage**: CSR (Compressed Sparse Row) and CSC (Compressed Sparse
23//!   Column) formats
24//! - **Block Diagonal Matrices**: Efficient storage and operations for block diagonal matrices
25//! - **Matrix Operations**: Sparse-sparse, sparse-dense, and sparse-vector multiplications
26//! - **Zero Threshold Support**: Automatic filtering of near-zero values for memory efficiency
27//! - **View-based API**: Efficient borrowing and slicing without allocation
28//! - **nalgebra Integration**: Seamless conversion between sparse and dense representations
29//!
30//! ## Quick Start
31//!
32//! ```rust
33//! use algebra_sparse::CsrMatrix;
34//! use nalgebra::DMatrix;
35//!
36//! // Create a dense matrix and convert to sparse
37//! let dense = DMatrix::from_row_slice(3, 3, &[
38//!     1.0, 0.0, 2.0,
39//!     0.0, 3.0, 0.0,
40//!     4.0, 0.0, 5.0,
41//! ]);
42//! let sparse = CsrMatrix::from_dense(dense.as_view());
43//!
44//! // Perform sparse matrix operations
45//! let result = sparse.as_view() * dense.column(0);
46//! println!("Result: {:?}", result);
47//! ```
48//!
49//! ## Matrix Formats
50//!
51//! This library supports several sparse matrix formats optimized for different use cases:
52//!
53//! - **CSR (Compressed Sparse Row)**: Efficient for row-wise operations and matrix-vector products
54//! - **CSC (Compressed Sparse Column)**: Efficient for column-wise operations
55//! - **Block Diagonal**: Optimized for block diagonal structure common in physical simulations
56//!
57//! ## Performance Considerations
58//!
59//! - Zero values below the threshold are automatically filtered during construction
60//! - View-based operations avoid unnecessary allocations
61//! - Sparse-sparse operations use efficient merging algorithms
62//! - Block diagonal operations leverage structure for optimal performance
63
64extern crate nalgebra as na;
65mod csm;
66mod csv;
67mod diagonal;
68pub mod ops;
69pub mod set;
70pub mod traits;
71
72pub use csm::*;
73pub use csv::*;
74pub use diagonal::*;
75pub use set::*;
76
77// pub const ZERO_THRESHOLD: Real = 1e-10;
78
79/// Trait for types that have a zero threshold.
80///
81/// This trait defines the threshold below which values are considered zero
82/// for sparse matrix operations. Values below this threshold are automatically
83/// filtered out during construction to maintain sparsity.
84pub trait ZeroThreshold {
85    /// Returns the zero threshold for this type.
86    fn zero_threshold() -> Self;
87}
88
89impl ZeroThreshold for f32 {
90    #[inline]
91    fn zero_threshold() -> Self {
92        1e-10
93    }
94}
95
96impl ZeroThreshold for f64 {
97    #[inline]
98    fn zero_threshold() -> Self {
99        1e-10
100    }
101}
102
103/// Trait combining nalgebra's RealField with ZeroThreshold for use in sparse operations.
104///
105/// This trait is implemented for all types that satisfy both `RealField` and `ZeroThreshold`.
106/// It's used as a constraint throughout the library for sparse matrix elements.
107pub trait Real: na::RealField + ZeroThreshold + Copy {}
108impl<T: na::RealField + ZeroThreshold + Copy> Real for T {}
algebra_sparse/lib.rs

algebra_sparse/
lib.rs
