Solving large systems of linear equations using sparse matrix methods.
```rust let mut m = sparse21::Matrix::from_entries(vec![ (0, 0, 1.0), (0, 1, 1.0), (0, 2, 1.0), (1, 1, 2.0), (1, 2, 5.0), (2, 0, 2.0), (2, 1, 5.0), (2, 2, -1.0), ]);
let soln = m.solve(vec![6.0, -4.0, 27.0]);
// => vec![5.0, 3.0, -2.0]
```
Sparse methods are primarily valuable for systems in which the number of non-zero entries is substantially less than the overall size of the matrix. Such situations are common in physical systems, including electronic circuit simulation. All elements of a sparse matrix are assumed to be zero-valued unless indicated otherwise.
Sparse21 exposes two primary data structures:
Matrix represents an f64-valued sparse matrixSystem represents a system of linear equations of the form Ax=b, including a Matrix (A) and right-hand-side Vec (b).Once matrices and systems have been created, their primary public method is solve, which returns a (dense) Vec solution-vector.
Sparse21 matrices can be constructed from a handful of data-sources
Matrix::new creates an empty matrix, to which elements can be added via the add_element and add_elements methods.
```rust let mut m = Matrix::new();
m.addelement(0, 0, 11.0); m.addelement(7, 0, 22.0); m.addelement(0, 7, 33.0); m.addelement(7, 7, 44.0); ```
```rust let mut m = Matrix::new();
m.add_elements(vec![(0, 0, 11.0), (7, 0, 22.0), (0, 7, 33.0), (7, 7, 44.0) ]); ```
The arguments to add_element are a row (usize), column (usize), and value (f64).
Adding elements (plural) via add_elements takes a vector of (usize, usize, f64) tuples, representing the row, col, and val.
Unlike common mathematical notation, all locations in sparse21 matrices and vectors are zero-indexed.
Adding a non-zero at the "first" matrix element therefore implies calling add_element(0, 0, val).
Creating a Matrix from data entries with Matrix::from_entries:
rust
let mut m = Matrix::from_entries(vec![
(2, 2, -1.0),
(2, 1, 5.0),
(2, 0, 2.0),
(1, 2, 5.0),
(1, 1, 2.0),
(0, 2, 1.0),
(0, 1, 1.0),
(0, 0, 1.0),
]);
The Matrix::identity method returns a new identity matrix of size (n x n):
rust
let mut m = Matrix::identity(3);
let soln = m.solve(vec![11.1, 30.3, 99.9]);
assert_eq!(soln, vec![11.1, 30.3, 99.9]);
Sparse21 matrices are built for solving equation-systems. The primary public method of a Matrix is solve(), which accepts a Vec right-hand-side as its sole argument, and returns a solution Vec of the same size.
You may have noticed all examples to date declare matrices as mut, perhaps unnecessarily. This is on purpose. The Matrix::solve method (un-rustily) modifies the matrix in-place. For larger matrices, the in-place modification saves orders of magnitude of memory, as well as time creating and destroying elements. While in-place self-modification falls out of line with the Rust ethos, it follows a long lineage of scientific computing tools for this and similar tasks.
So: in order to be solved, matrices must be declared mut.
Sparse21 equation-systems can be loaded directly from a (custom-format) file including the elements and RHS.
rust
let s = sparse21::System::from_file(Path::new("my_matrix.mat"))?;
let soln = s.solve();
It is often more convenient to split a sparse21::System into its constituent matrix and RHS. The split method returns a tuple of the two:
```rust let s = sparse21::System::from_file(&p)?;
// Split into parts, and solve
// More or less equivalent to s.solve()
let (mut mat, rhs) = s.split();
let res = mat.solve(rhs);
```