numr 0.5.1

High-performance numerical computing with multi-backend GPU acceleration (CPU/CUDA/WebGPU)
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
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141

//! Sparse format definitions and traits

use crate::dtype::DType;

/// Sparse matrix storage format
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum SparseFormat {
    /// Coordinate format (COO)
    ///
    /// Stores explicit (row, col, value) triplets.
    /// Best for: construction, format conversion, random access insertion
    /// Storage: O(3 * nnz)
    Coo,

    /// Compressed Sparse Row (CSR)
    ///
    /// Row pointers + column indices + values.
    /// Best for: row slicing, SpMV, most sparse operations
    /// Storage: O(2 * nnz + nrows + 1)
    Csr,

    /// Compressed Sparse Column (CSC)
    ///
    /// Column pointers + row indices + values.
    /// Best for: column slicing, transposed operations
    /// Storage: O(2 * nnz + ncols + 1)
    Csc,
}

impl SparseFormat {
    /// Returns true if format is efficient for row operations
    #[inline]
    pub fn is_row_major(&self) -> bool {
        matches!(self, SparseFormat::Csr)
    }

    /// Returns true if format is efficient for column operations
    #[inline]
    pub fn is_col_major(&self) -> bool {
        matches!(self, SparseFormat::Csc)
    }

    /// Returns the format name as a string
    pub fn name(&self) -> &'static str {
        match self {
            SparseFormat::Coo => "COO",
            SparseFormat::Csr => "CSR",
            SparseFormat::Csc => "CSC",
        }
    }
}

impl std::fmt::Display for SparseFormat {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.name())
    }
}

/// Trait for sparse storage backends
///
/// This trait defines the common interface for all sparse storage formats.
/// Each format (COO, CSR, CSC) implements this trait.
pub trait SparseStorage: Sized {
    /// Returns the sparse format type
    fn format(&self) -> SparseFormat;

    /// Returns the shape as [nrows, ncols]
    fn shape(&self) -> [usize; 2];

    /// Returns the number of rows
    #[inline]
    fn nrows(&self) -> usize {
        self.shape()[0]
    }

    /// Returns the number of columns
    #[inline]
    fn ncols(&self) -> usize {
        self.shape()[1]
    }

    /// Returns the number of non-zero elements
    fn nnz(&self) -> usize;

    /// Returns the data type of values
    fn dtype(&self) -> DType;

    /// Returns the sparsity ratio (fraction of zeros)
    ///
    /// Sparsity = 1.0 - (nnz / total_elements)
    #[inline]
    fn sparsity(&self) -> f64 {
        let total = (self.nrows() * self.ncols()) as f64;
        if total == 0.0 {
            0.0
        } else {
            1.0 - (self.nnz() as f64 / total)
        }
    }

    /// Returns the density ratio (fraction of non-zeros)
    ///
    /// Density = nnz / total_elements = 1.0 - sparsity
    #[inline]
    fn density(&self) -> f64 {
        1.0 - self.sparsity()
    }

    /// Returns true if the matrix is empty (no non-zeros)
    #[inline]
    fn is_empty(&self) -> bool {
        self.nnz() == 0
    }

    /// Returns the memory usage in bytes (approximate)
    fn memory_usage(&self) -> usize;
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_sparse_format_display() {
        assert_eq!(SparseFormat::Coo.to_string(), "COO");
        assert_eq!(SparseFormat::Csr.to_string(), "CSR");
        assert_eq!(SparseFormat::Csc.to_string(), "CSC");
    }

    #[test]
    fn test_format_properties() {
        assert!(!SparseFormat::Coo.is_row_major());
        assert!(SparseFormat::Csr.is_row_major());
        assert!(!SparseFormat::Csc.is_row_major());

        assert!(!SparseFormat::Coo.is_col_major());
        assert!(!SparseFormat::Csr.is_col_major());
        assert!(SparseFormat::Csc.is_col_major());
    }
}