neco-sparse 0.1.0

Lightweight COO / CSR sparse matrix types
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

# neco-sparse

[日本語](README-ja.md)

Lightweight COO and CSR sparse matrix types for assembling sparse operators and iterating rows efficiently in caller-side sparse linear algebra code.

## Matrix formats

neco-sparse focuses on two storage formats:

- `CooMat<T>` for assembly, where entries are pushed as `(row, col, value)` triplets
- `CsrMat<T>` for computation, where rows are contiguous and row-wise traversal runs in `O(nnz)`

The common workflow is to accumulate entries in COO, allow duplicates during assembly, and convert once to CSR for iteration, diagonal extraction, submatrix construction, or caller-side SpMV.

## Usage

### Build CSR directly

```rust
use neco_sparse::CsrMat;

let csr = CsrMat::try_from_csr_data(
    2,
    3,
    vec![0, 2, 3],
    vec![0, 2, 1],
    vec![1.0, 4.0, 3.0],
).unwrap();

assert_eq!(csr.nnz(), 3);
assert_eq!(csr.get(0, 2), Some(&4.0));
```

### Assemble in COO, then convert

```rust
use neco_sparse::{CooMat, CsrMat};

let mut coo = CooMat::new(3, 3);
coo.push(0, 0, 2.0);
coo.push(1, 2, 5.0);
coo.push(0, 0, 1.0);

let csr = CsrMat::from(&coo);
assert_eq!(csr.get(0, 0), Some(&3.0));
```

### Iterate rows and build auxiliary matrices

```rust
use neco_sparse::CsrMat;

let eye = CsrMat::identity(4);
let zeros = CsrMat::zeros(3, 5);

for row in eye.row_iter() {
    for (&col, &val) in row.col_indices().iter().zip(row.values()) {
        println!("col={col}, val={val}");
    }
}

assert_eq!(zeros.nnz(), 0);
```

### Extract diagonals and submatrices

```rust
use neco_sparse::{CooMat, CsrMat};

let mut coo = CooMat::new(3, 3);
coo.push(0, 0, 4.0);
coo.push(0, 2, 1.0);
coo.push(1, 1, 5.0);
coo.push(2, 0, 2.0);
coo.push(2, 2, 6.0);

let csr = CsrMat::from(&coo);
let diag = csr.diagonal().unwrap();
let sub = csr.submatrix(&[2, 0], &[2, 0]).unwrap();

assert_eq!(diag, vec![4.0, 5.0, 6.0]);
assert_eq!(sub.row(0).values(), &[6.0, 2.0]);
```

## API

| Item | Description |
|------|-------------|
| `CooMat<T>` | Coordinate-format sparse matrix for assembly |
| `CooMat::new(rows, cols)` | Create an empty COO matrix |
| `CooMat::push(row, col, value)` | Add one triplet entry |
| `CsrMat<T>` | Compressed sparse row matrix for computation |
| `CsrMat::try_from_csr_data(...)` | Construct CSR directly from raw arrays with validation |
| `From<&CooMat<T>> for CsrMat<T>` | Convert COO to CSR and sum duplicate coordinates |
| `CsrMat::row(i)` / `row_iter()` | Access one row or iterate rows |
| `CsrRow<'a, T>` | Borrowed row view with column indices and values |
| `CsrMat::identity(n)` / `zeros(rows, cols)` | Convenience constructors for `f64` matrices |
| `CsrMat::linear_combination(alpha, other, beta)` | Build `alpha * self + beta * other` when both CSR patterns match |
| `CsrMat::diagonal()` | Extract the diagonal entries and return `Err` when a required entry is missing |
| `CsrMat::submatrix(rows, cols)` | Build a CSR submatrix from unique row/column index lists |

## License

MIT