qfall_math/rational/mat_q/
default.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//! Initialize a [`MatQ`] with common defaults, e.g., zero and identity.
10
11use super::MatQ;
12use crate::utils::index::evaluate_indices;
13use flint_sys::fmpq_mat::{fmpq_mat_init, fmpq_mat_one};
14use std::{fmt::Display, mem::MaybeUninit};
15
16impl MatQ {
17    /// Creates a new matrix with `num_rows` rows, `num_cols` columns and
18    /// zeros as entries.
19    ///
20    /// Parameters:
21    /// - `num_rows`: number of rows the new matrix should have
22    /// - `num_cols`: number of columns the new matrix should have
23    ///
24    /// Returns a new [`MatQ`] instance of the provided dimensions.
25    ///
26    /// # Examples
27    /// ```
28    /// use qfall_math::rational::MatQ;
29    ///
30    /// let matrix = MatQ::new(5, 10);
31    /// ```
32    ///
33    /// # Panics ...
34    /// - if the number of rows or columns is negative, `0`, or does not fit into an [`i64`].
35    pub fn new(
36        num_rows: impl TryInto<i64> + Display,
37        num_cols: impl TryInto<i64> + Display,
38    ) -> Self {
39        let (num_rows_i64, num_cols_i64) = evaluate_indices(num_rows, num_cols).unwrap();
40
41        assert!(
42            num_rows_i64 != 0 && num_cols_i64 != 0,
43            "A matrix can not contain 0 rows or 0 columns."
44        );
45
46        let mut matrix = MaybeUninit::uninit();
47        unsafe {
48            fmpq_mat_init(matrix.as_mut_ptr(), num_rows_i64, num_cols_i64);
49
50            // Construct MatQ from previously initialized fmpq_mat
51            MatQ {
52                matrix: matrix.assume_init(),
53            }
54        }
55    }
56
57    /// Generate a `num_rows` times `num_columns` matrix with `1` on the
58    /// diagonal and `0` anywhere else.
59    ///
60    /// Parameters:
61    /// - `rum_rows`: the number of rows of the identity matrix
62    /// - `num_columns`: the number of columns of the identity matrix
63    ///
64    /// Returns a matrix with `1` across the diagonal and `0` anywhere else.
65    ///
66    /// # Examples
67    /// ```
68    /// use qfall_math::rational::MatQ;
69    ///
70    /// let matrix = MatQ::identity(2, 3);
71    ///
72    /// let identity = MatQ::identity(10, 10);
73    /// ```
74    ///
75    /// # Panics ...
76    /// - if the provided number of rows and columns are not suited to create a matrix.
77    ///   For further information see [`MatQ::new`].
78    pub fn identity(
79        num_rows: impl TryInto<i64> + Display,
80        num_cols: impl TryInto<i64> + Display,
81    ) -> Self {
82        let mut out = MatQ::new(num_rows, num_cols);
83        unsafe { fmpq_mat_one(&mut out.matrix) };
84        out
85    }
86}
87
88#[cfg(test)]
89mod test_new {
90    use crate::rational::MatQ;
91
92    /// Ensure that initialization works.
93    #[test]
94    fn initialization() {
95        let _ = MatQ::new(2, 2);
96    }
97
98    /// Ensure that a new zero matrix fails with `0` as `num_cols`.
99    #[should_panic]
100    #[test]
101    fn error_zero_num_cols() {
102        let _ = MatQ::new(1, 0);
103    }
104
105    /// Ensure that a new zero matrix fails with `0` as `num_rows`.
106    #[should_panic]
107    #[test]
108    fn error_zero_num_rows() {
109        let _ = MatQ::new(0, 1);
110    }
111}
112
113#[cfg(test)]
114mod test_set_one {
115    use crate::{
116        rational::{MatQ, Q},
117        traits::MatrixGetEntry,
118    };
119
120    /// Tests if an identity matrix is set from a zero matrix.
121    #[test]
122    fn identity() {
123        let matrix = MatQ::identity(10, 10);
124
125        for i in 0..10 {
126            for j in 0..10 {
127                if i != j {
128                    assert_eq!(Q::ZERO, matrix.get_entry(i, j).unwrap());
129                } else {
130                    assert_eq!(Q::ONE, matrix.get_entry(i, j).unwrap());
131                }
132            }
133        }
134    }
135
136    /// Tests if function works for a non-square matrix
137    #[test]
138    fn non_square_works() {
139        let matrix = MatQ::identity(10, 7);
140
141        for i in 0..10 {
142            for j in 0..7 {
143                if i != j {
144                    assert_eq!(Q::ZERO, matrix.get_entry(i, j).unwrap());
145                } else {
146                    assert_eq!(Q::ONE, matrix.get_entry(i, j).unwrap());
147                }
148            }
149        }
150
151        let matrix = MatQ::identity(7, 10);
152
153        for i in 0..7 {
154            for j in 0..10 {
155                if i != j {
156                    assert_eq!(Q::ZERO, matrix.get_entry(i, j).unwrap());
157                } else {
158                    assert_eq!(Q::ONE, matrix.get_entry(i, j).unwrap());
159                }
160            }
161        }
162    }
163}
qfall_math/rational/mat_q/default.rs

qfall_math/rational/mat_q/
default.rs
