qfall_math/rational/mat_q/
inverse.rs

1// Copyright © 2023 Marcel Luca Schmidt
2//
3// This file is part of qFALL-math.
4//
5// qFALL-math is free software: you can redistribute it and/or modify it under
6// the terms of the Mozilla Public License Version 2.0 as published by the
7// Mozilla Foundation. See <https://mozilla.org/en-US/MPL/2.0/>.
8
9//! This module contains the implementation of the `inverse` function.
10
11use super::MatQ;
12use crate::traits::MatrixDimensions;
13use flint_sys::fmpq_mat::fmpq_mat_inv;
14
15impl MatQ {
16    /// Returns the inverse of the matrix if it exists (is square and
17    /// has a determinant unequal to `0`) and `None` otherwise.
18    ///
19    /// # Examples
20    /// ```
21    /// use qfall_math::rational::MatQ;
22    /// use qfall_math::traits::*;
23    /// use std::str::FromStr;
24    ///
25    /// let mut matrix = MatQ::from_str("[[1/2, 2],[3/4, 4]]").unwrap();
26    /// let matrix_invert = matrix.inverse().unwrap();
27    /// ```
28    pub fn inverse(&self) -> Option<MatQ> {
29        // check if matrix is square
30        if self.get_num_rows() != self.get_num_columns() {
31            return None;
32        }
33
34        // check if determinant is not `0`, create new matrix to store inverted result in
35        let mut out = MatQ::new(self.get_num_rows(), self.get_num_columns());
36        match unsafe { fmpq_mat_inv(&mut out.matrix, &self.matrix) } {
37            0 => None,
38            _ => Some(out),
39        }
40    }
41}
42
43#[cfg(test)]
44mod test_inverse {
45    use crate::rational::MatQ;
46    use std::str::FromStr;
47
48    /// Test whether `inverse` correctly calculates an inverse matrix
49    #[test]
50    fn inverse_works() {
51        let mat_1 = MatQ::from_str("[[5/3, 2, 0],[6, 1, 0],[0, 0, 1/2]]").unwrap();
52        let mat_2 = MatQ::from_str(&format!("[[{}]]", i64::MAX)).unwrap();
53        let mat_3 = MatQ::from_str("[[-1, 0],[0, 1]]").unwrap();
54
55        let cmp_inv_1 = MatQ::from_str("[[-3/31, 6/31, 0],[18/31, -5/31, 0],[0, 0, 2]]").unwrap();
56        let cmp_inv_2 = MatQ::from_str(&format!("[[1/{}]]", i64::MAX)).unwrap();
57        let cmp_inv_3 = MatQ::from_str("[[-1, 0],[0, 1]]").unwrap();
58
59        let inv_1 = mat_1.inverse().unwrap();
60        let inv_2 = mat_2.inverse().unwrap();
61        let inv_3 = mat_3.inverse().unwrap();
62
63        assert_eq!(cmp_inv_1, inv_1);
64        assert_eq!(cmp_inv_2, inv_2);
65        assert_eq!(cmp_inv_3, inv_3);
66    }
67
68    /// Check if the multiplication of inverse and matrix result in an identity matrix
69    #[test]
70    fn inverse_correct() {
71        let mat = MatQ::from_str("[[5/6, 2],[2/9, 1/3]]").unwrap();
72        let cmp = MatQ::identity(2, 2);
73
74        let inv = mat.inverse().unwrap();
75        let diag = &mat * &inv;
76
77        assert_eq!(cmp, diag);
78    }
79
80    /// Ensure that a matrix that is not square yields `None` on inversion.
81    #[test]
82    fn inv_none_not_squared() {
83        let mat_1 = MatQ::from_str("[[1, 0, 1],[0, 1, 1]]").unwrap();
84        let mat_2 = MatQ::from_str("[[1, 0],[0, 1],[1, 0]]").unwrap();
85
86        assert!(mat_1.inverse().is_none());
87        assert!(mat_2.inverse().is_none());
88    }
89
90    /// Ensure that a matrix that has a determinant of `0` yields `None` on inversion.
91    #[test]
92    fn inv_none_det_zero() {
93        let mat = MatQ::from_str("[[2, 0],[0, 0]]").unwrap();
94
95        assert!(mat.inverse().is_none());
96    }
97}
qfall_math/rational/mat_q/inverse.rs

qfall_math/rational/mat_q/
inverse.rs
