algebra-sparse

Efficient sparse linear algebra library built on top of [nalgebra], providing high-performance sparse matrix and vector operations for scientific computing and physics simulations.

Features

• Compressed Sparse Matrix Storage: Support for both CSR (Compressed Sparse Row) and CSC (Compressed Sparse Column) formats
• Block Diagonal Matrices: Optimized storage and operations for block diagonal structures common in physical simulations
• Matrix Operations: Comprehensive sparse-sparse, sparse-dense, and sparse-vector multiplications
• Zero Threshold Support: Automatic filtering of near-zero values for memory efficiency
• View-based API: Efficient borrowing and slicing without allocation
• nalgebra Integration: Seamless conversion between sparse and dense representations
• Matrix Sets: Efficient storage of multiple sparse matrices in a single data structure

Quick Start

Add this to your Cargo.toml:

[dependencies]
algebra-sparse = "*"

Basic Usage

use algebra_sparse::CsrMatrix;
use nalgebra::DMatrix;

// Create a dense matrix and convert to sparse
let dense = DMatrix::from_row_slice(3, 3, &[
    1.0, 0.0, 2.0,
    0.0, 3.0, 0.0,
    4.0, 0.0, 5.0,
]);

// Convert to CSR format (automatically filters zeros)
let sparse = CsrMatrix::from_dense(dense.as_view());

// Perform sparse matrix-vector multiplication
let vector = nalgebra::DVector::from_vec(vec![1.0, 2.0, 3.0]);
let result = sparse.as_view() * vector;

println!("Result: {:?}", result);

Block Diagonal Matrices

use algebra_sparse::DiagonalBlockMatrix;

// Create a block diagonal matrix with 2x2 and 3x3 blocks
// Blocks are stored in column-major order
let block_values = vec![
    1.0, 3.0, 2.0, 4.0,           // 2x2 block [1 2; 3 4]
    5.0, 8.0, 11.0, 6.0, 9.0, 12.0, 7.0, 10.0, 13.0  // 3x3 block
];
let block_sizes = [2, 3];
let matrix = DiagonalBlockMatrix::from_block_values(block_values, &block_sizes);

println!("Matrix shape: {}x{}", matrix.nrows(), matrix.ncols());

Building Sparse Matrices

use algebra_sparse::CsrMatrix;

let mut matrix = CsrMatrix::new(4); // 4 columns

// Add first row
let mut builder = matrix.new_row_builder(1e-10);
builder.push(0, 1.0);
builder.push(2, 2.0);
// Row is automatically added when builder is dropped

// Add second row
let mut builder = matrix.new_row_builder(1e-10);
builder.push(1, 3.0);
builder.push(3, 4.0);

println!("Number of rows: {}", matrix.as_view().nrows());

Matrix Formats

CSR (Compressed Sparse Row)

• Optimized for row-wise operations
• Efficient for matrix-vector products
• Fast row access and iteration

CSC (Compressed Sparse Column)

• Optimized for column-wise operations
• Efficient for column-based computations
• Fast column access and iteration

Block Diagonal

• Optimized for block diagonal structures
• Common in physical simulations and FEM
• Efficient storage for structured sparsity

Performance Considerations

• View-based Operations: No unnecessary allocations for read-only access
• Efficient Algorithms: Optimized sparse-sparse and sparse-dense operations
• Memory Layout: Designed for cache-friendly access patterns

Examples

Sparse Matrix Multiplication

use algebra_sparse::CsrMatrix;
use nalgebra::DMatrix;

let a_dense = DMatrix::from_row_slice(2, 3, &[1.0, 0.0, 2.0, 0.0, 3.0, 0.0]);
let b_dense = DMatrix::from_row_slice(3, 2, &[1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);

let a = CsrMatrix::from_dense(a_dense.as_view());
let b = CsrMatrix::from_dense(b_dense.transpose().as_view());

let result = a.as_view() * b.transpose();
println!("Sparse multiplication result:");
println!("{}", result.to_dense());

Matrix Transposition

use algebra_sparse::CsrMatrix;
use nalgebra::DMatrix;

let dense = DMatrix::from_row_slice(2, 3, &[1.0, 2.0, 3.0, 4.0, 5.0, 6.0]);
let csr = CsrMatrix::from_dense(dense.as_view());

// Transpose CSR to CSC
let csc = csr.as_view().transpose();

println!("Original shape: {:?}", csr.as_view().shape());
println!("Transposed shape: {:?}", csc.shape());

Documentation

For comprehensive API documentation, visit docs.rs/algebra-sparse.