sparse_bin_mat/lib.rs
1//! A sparse implementation of a binary matrix optimized for row operations.
2//!
3//! The main objects of this crate are [`matrices`](crate::SparseBinMat) and [`vectors`](crate::SparseBinVecBase).
4//! All elements in a binary matrix or vector are element of the binary field GF2.
5//! That is, they are either 0 or 1 and addition is modulo 2.
6//!
7//! # Quick start
8//!
9//! To instanciate a matrix, you need to specify the number of columns as well
10//! as the position of 1 in each rows.
11//!
12//! ```
13//! use sparse_bin_mat::SparseBinMat;
14//!
15//! // This is the matrix
16//! // 1 0 1 0 1
17//! // 0 1 0 1 0
18//! // 0 0 1 0 0
19//! let matrix = SparseBinMat::new(5, vec![vec![0, 2, 4], vec![1, 3], vec![2]]);
20//! ```
21//!
22//! It is easy to access elements or rows of a matrix. However,
23//! since the matrix are optimized for row operations, you need
24//! to transpose the matrix if you want to perform column operations.
25//!
26//! ```
27//! # use sparse_bin_mat::{SparseBinMat, BinNum};
28//! let matrix = SparseBinMat::new(5, vec![vec![0, 2, 4], vec![1, 3], vec![2]]);
29//! assert_eq!(matrix.row(1).unwrap().as_slice(), [1, 3].as_ref());
30//! assert_eq!(matrix.get(0, 0), Some(BinNum::new(1)));
31//! assert_eq!(matrix.get(0, 1), Some(BinNum::new(0)));
32//! // The element (0, 7) is out of bound for a 3 x 5 matrix.
33//! assert_eq!(matrix.get(0, 7), None);
34//! ```
35//!
36//! Addition and multiplication are implemented between matrix references.
37//!
38//! ```
39//! # use sparse_bin_mat::SparseBinMat;
40//! let matrix = SparseBinMat::new(3, vec![vec![0, 1], vec![1, 2], vec![0, 2]]);
41//! let identity = SparseBinMat::identity(3);
42//!
43//! let sum = SparseBinMat::new(3, vec![vec![1], vec![2], vec![0]]);
44//! assert_eq!(&matrix + &identity, sum);
45//!
46//! assert_eq!(&matrix * &identity, matrix);
47//! ```
48//!
49//! Many useful operations and decompositions are implemented.
50//! These include, but are not limited to
51//! - [`rank`](SparseBinMat::rank),
52//! - [`echelon form`](SparseBinMat::echelon_form),
53//! - [`nullspace`](SparseBinMat::nullspace),
54//! - [`tranposition`](SparseBinMat::transposed),
55//! - [`horizontal`](SparseBinMat::horizontal_concat_with) and
56//! [`vertical`](SparseBinMat::vertical_concat_with) concatenations,
57//! - and more ...
58//!
59//! Operations are implemented as I need them,
60//! feel welcome to raise an issue if you need a new functionnality.
61
62mod binary_number;
63pub use binary_number::BinNum;
64
65pub mod error;
66
67mod matrix;
68pub use matrix::{NonTrivialElements, Rows, SparseBinMat};
69
70mod vector;
71pub use vector::{NonTrivialPositions, SparseBinSlice, SparseBinVec, SparseBinVecBase};