numrs2 0.3.1

A Rust implementation inspired by NumPy for numerical computing (NumRS2)
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
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255

#![allow(deprecated)]

use numrs2::prelude::*;

fn main() {
    println!("NumRS Sparse Array Examples");
    println!("==========================\n");

    // 1. Basic sparse array operations
    println!("1. Basic Sparse Array Operations");
    println!("-------------------------------");

    // Create a sparse array
    let mut sparse = SparseArray::new(&[5, 5]);

    // Set some values
    sparse.set(&[0, 0], 1.0).unwrap();
    sparse.set(&[1, 1], 2.0).unwrap();
    sparse.set(&[2, 2], 3.0).unwrap();
    sparse.set(&[3, 3], 4.0).unwrap();
    sparse.set(&[4, 4], 5.0).unwrap();
    sparse.set(&[0, 4], 6.0).unwrap();
    sparse.set(&[4, 0], 7.0).unwrap();

    println!("Created a 5x5 sparse array with diagonal values and two off-diagonal values");
    println!("Non-zero count: {}", sparse.nnz());
    println!("Density: {:.2}%", sparse.density() * 100.0);

    // Convert to dense for display
    let dense = sparse.to_array();
    println!("\nAs dense array:");
    print_2d_array(&dense);

    // Access elements
    println!("\nAccessing elements:");
    println!("sparse[0, 0] = {}", sparse.get(&[0, 0]).unwrap());
    println!("sparse[2, 2] = {}", sparse.get(&[2, 2]).unwrap());
    println!("sparse[0, 4] = {}", sparse.get(&[0, 4]).unwrap());
    println!("sparse[1, 3] = {}", sparse.get(&[1, 3]).unwrap()); // Should be 0.0

    // 2. Sparse array arithmetic
    println!("\n2. Sparse Array Arithmetic");
    println!("-------------------------");

    // Create another sparse array
    let mut sparse2 = SparseArray::new(&[5, 5]);
    sparse2.set(&[0, 0], 5.0).unwrap();
    sparse2.set(&[1, 1], 4.0).unwrap();
    sparse2.set(&[2, 2], 3.0).unwrap();
    sparse2.set(&[3, 3], 2.0).unwrap();
    sparse2.set(&[4, 4], 1.0).unwrap();
    sparse2.set(&[1, 3], 7.0).unwrap();

    println!("Second sparse array");
    let dense2 = sparse2.to_array();
    println!("Non-zero count: {}", sparse2.nnz());
    print_2d_array(&dense2);

    // Addition
    match sparse.add(&sparse2) {
        Ok(sum) => {
            println!("\nSum of sparse arrays:");
            println!("Non-zero count: {}", sum.nnz());
            let dense_sum = sum.to_array();
            print_2d_array(&dense_sum);
        }
        Err(e) => println!("Error: {}", e),
    }

    // Element-wise multiplication
    match sparse.multiply(&sparse2) {
        Ok(product) => {
            println!("\nElement-wise product of sparse arrays:");
            println!("Non-zero count: {}", product.nnz());
            let dense_product = product.to_array();
            print_2d_array(&dense_product);
        }
        Err(e) => println!("Error: {}", e),
    }

    // Scalar multiplication
    let scaled = sparse.multiply_scalar(2.0);
    println!("\nSparse array multiplied by 2.0:");
    println!("Non-zero count: {}", scaled.nnz());
    let dense_scaled = scaled.to_array();
    print_2d_array(&dense_scaled);

    // 3. Sparse matrices and specialized formats
    println!("\n3. Sparse Matrix Formats");
    println!("-----------------------");

    // Create a sparse matrix
    match SparseMatrix::new(&[4, 4]) {
        Ok(mut sparse_matrix) => {
            // Set some values
            sparse_matrix.set(0, 0, 1.0).unwrap();
            sparse_matrix.set(1, 1, 2.0).unwrap();
            sparse_matrix.set(2, 2, 3.0).unwrap();
            sparse_matrix.set(3, 3, 4.0).unwrap();
            sparse_matrix.set(0, 3, 5.0).unwrap();
            sparse_matrix.set(3, 0, 6.0).unwrap();

            println!("Original sparse matrix (COO format):");
            let dense_matrix = sparse_matrix.to_array();
            print_2d_array(&dense_matrix);

            // Convert to CSR format
            match sparse_matrix.to_csr() {
                Ok(_) => {
                    println!("\nConverted to CSR (Compressed Sparse Row) format");
                    println!(
                        "This format is efficient for row operations and matrix-vector products"
                    );

                    // Verify data is still accessible
                    println!("\nVerifying elements:");
                    println!("matrix[0, 0] = {}", sparse_matrix.get(0, 0).unwrap());
                    println!("matrix[2, 2] = {}", sparse_matrix.get(2, 2).unwrap());
                    println!("matrix[0, 3] = {}", sparse_matrix.get(0, 3).unwrap());
                }
                Err(e) => println!("Error converting to CSR: {}", e),
            }

            // Convert to CSC format
            match sparse_matrix.to_csc() {
                Ok(_) => {
                    println!("\nConverted to CSC (Compressed Sparse Column) format");
                    println!("This format is efficient for column operations");

                    // Verify data is still accessible
                    println!("\nVerifying elements:");
                    println!("matrix[0, 0] = {}", sparse_matrix.get(0, 0).unwrap());
                    println!("matrix[3, 0] = {}", sparse_matrix.get(3, 0).unwrap());
                }
                Err(e) => println!("Error converting to CSC: {}", e),
            }
        }
        Err(e) => println!("Error creating sparse matrix: {}", e),
    }

    // 4. Special sparse matrix constructors
    println!("\n4. Special Sparse Matrix Constructors");
    println!("-----------------------------------");

    // Identity matrix
    match SparseMatrix::eye(4) {
        Ok(eye) => {
            println!("Sparse identity matrix (4x4):");
            println!("Non-zero count: {}", eye.nnz());
            let dense_eye = eye.to_array();
            print_2d_array(&dense_eye);
        }
        Err(e) => println!("Error creating identity matrix: {}", e),
    }

    // Diagonal matrix
    match SparseMatrix::diag(&[1.0, 2.0, 3.0, 4.0, 5.0]) {
        Ok(diag) => {
            println!("\nSparse diagonal matrix from vector [1, 2, 3, 4, 5]:");
            println!("Non-zero count: {}", diag.nnz());
            let dense_diag = diag.to_array();
            print_2d_array(&dense_diag);
        }
        Err(e) => println!("Error creating diagonal matrix: {}", e),
    }

    // 5. Sparse matrix operations
    println!("\n5. Sparse Matrix Operations");
    println!("---------------------------");

    // Create two sparse matrices for multiplication
    match SparseMatrix::new(&[3, 3]) {
        Ok(mut a) => {
            a.set(0, 0, 1.0).unwrap();
            a.set(0, 1, 2.0).unwrap();
            a.set(1, 0, 3.0).unwrap();
            a.set(1, 1, 4.0).unwrap();
            a.set(2, 2, 5.0).unwrap();

            match SparseMatrix::new(&[3, 2]) {
                Ok(mut b) => {
                    b.set(0, 0, 6.0).unwrap();
                    b.set(0, 1, 7.0).unwrap();
                    b.set(1, 0, 8.0).unwrap();
                    b.set(1, 1, 9.0).unwrap();

                    println!("Matrix A:");
                    print_2d_array(&a.to_array());

                    println!("\nMatrix B:");
                    print_2d_array(&b.to_array());

                    // Matrix multiplication
                    match a.matmul(&b) {
                        Ok(c) => {
                            println!("\nMatrix C = A * B:");
                            println!("Shape: {:?}", c.shape());
                            println!("Non-zero count: {}", c.nnz());
                            print_2d_array(&c.to_array());

                            // Verify: should be [[22, 25], [50, 57], [0, 0]]
                        }
                        Err(e) => println!("Error in matrix multiplication: {}", e),
                    }

                    // Transpose
                    match a.transpose() {
                        Ok(at) => {
                            println!("\nTranspose of A:");
                            print_2d_array(&at.to_array());
                        }
                        Err(e) => println!("Error computing transpose: {}", e),
                    }
                }
                Err(e) => println!("Error creating matrix B: {}", e),
            }
        }
        Err(e) => println!("Error creating matrix A: {}", e),
    }

    // 6. Performance benefits of sparse arrays
    println!("\n6. Performance Benefits of Sparse Arrays");
    println!("--------------------------------------");
    println!("In a large-scale application, sparse arrays provide significant memory savings");
    println!("For example, a 1,000,000 x 1,000,000 matrix with 0.001% non-zeros:");
    println!("  - Dense: Would require 8 TB of memory (8 bytes per element)");
    println!("  - Sparse: Would require ~8 GB of memory (storing only non-zeros)");
    println!("\nSparse matrices are particularly useful for:");
    println!("  - Large network/graph problems");
    println!("  - Finite element analysis");
    println!("  - Document-term matrices in text processing");
    println!("  - Machine learning with sparse features");
}

// Helper function to print 2D arrays
fn print_2d_array(array: &Array<f64>) {
    let shape = array.shape();
    if shape.len() != 2 {
        println!("Not a 2D array");
        return;
    }

    let rows = shape[0];
    let cols = shape[1];
    let data = array.to_vec();

    for i in 0..rows {
        for j in 0..cols {
            let val = data[i * cols + j];
            // Format with fixed width for better visualization
            print!("{:5.1} ", val);
        }
        println!();
    }
}