qfall_math/integer/mat_poly_over_z/
default.rs

1// Copyright © 2023 Marvin Beckmann
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 [`MatPolyOverZ`] with common defaults, e.g., zero and identity.
10
11use super::MatPolyOverZ;
12use crate::utils::index::evaluate_indices;
13use flint_sys::fmpz_poly_mat::{fmpz_poly_mat_init, fmpz_poly_mat_one};
14use std::{fmt::Display, mem::MaybeUninit};
15
16impl MatPolyOverZ {
17    /// Creates a new matrix with `num_rows` rows, `num_cols` columns and
18    /// zeros as entries, where each entry is a [`PolyOverZ`](crate::integer::PolyOverZ).
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 [`MatPolyOverZ`] instance of the provided dimensions.
25    ///
26    /// # Examples
27    /// ```
28    /// use qfall_math::integer::MatPolyOverZ;
29    ///
30    /// let matrix = MatPolyOverZ::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            fmpz_poly_mat_init(matrix.as_mut_ptr(), num_rows_i64, num_cols_i64);
49
50            // Construct MatPolyOverZ from previously initialized fmpz_poly_mat
51            MatPolyOverZ {
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::integer::MatPolyOverZ;
69    ///
70    /// let matrix = MatPolyOverZ::identity(2, 3);
71    ///
72    /// let identity = MatPolyOverZ::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 [`MatPolyOverZ::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 = MatPolyOverZ::new(num_rows, num_cols);
83        unsafe { fmpz_poly_mat_one(&mut out.matrix) };
84        out
85    }
86}
87
88#[cfg(test)]
89mod test_new {
90    use crate::{integer::MatPolyOverZ, traits::MatrixGetEntry};
91
92    /// Ensure that entries of a new matrix are `0`.
93    #[test]
94    fn entry_zero() {
95        let matrix = MatPolyOverZ::new(2, 2);
96
97        let entry_1 = matrix.get_entry(0, 0).unwrap();
98        let entry_2 = matrix.get_entry(0, 1).unwrap();
99        let entry_3 = matrix.get_entry(1, 0).unwrap();
100        let entry_4 = matrix.get_entry(1, 1).unwrap();
101
102        assert_eq!("0", entry_1.to_string());
103        assert_eq!("0", entry_2.to_string());
104        assert_eq!("0", entry_3.to_string());
105        assert_eq!("0", entry_4.to_string());
106    }
107
108    /// Ensure that a new zero matrix fails with `0` as `num_cols`.
109    #[should_panic]
110    #[test]
111    fn error_zero_num_cols() {
112        let _ = MatPolyOverZ::new(1, 0);
113    }
114
115    /// Ensure that a new zero matrix fails with `0` as `num_rows`.
116    #[should_panic]
117    #[test]
118    fn error_zero_num_rows() {
119        let _ = MatPolyOverZ::new(0, 1);
120    }
121}
122
123#[cfg(test)]
124mod test_identity {
125    use crate::{integer::MatPolyOverZ, traits::MatrixGetEntry};
126
127    /// Tests if an identity matrix is set from a zero matrix.
128    #[test]
129    fn identity() {
130        let matrix = MatPolyOverZ::identity(10, 10);
131
132        for i in 0..10 {
133            for j in 0..10 {
134                if i != j {
135                    assert!(matrix.get_entry(i, j).unwrap().is_zero());
136                } else {
137                    assert!(matrix.get_entry(i, j).unwrap().is_one());
138                }
139            }
140        }
141    }
142
143    /// Tests if function works for a non-square matrix
144    #[test]
145    fn non_square_works() {
146        let matrix = MatPolyOverZ::identity(10, 7);
147
148        for i in 0..10 {
149            for j in 0..7 {
150                if i != j {
151                    assert!(matrix.get_entry(i, j).unwrap().is_zero());
152                } else {
153                    assert!(matrix.get_entry(i, j).unwrap().is_one());
154                }
155            }
156        }
157
158        let matrix = MatPolyOverZ::identity(7, 10);
159
160        for i in 0..7 {
161            for j in 0..10 {
162                if i != j {
163                    assert!(matrix.get_entry(i, j).unwrap().is_zero());
164                } else {
165                    assert!(matrix.get_entry(i, j).unwrap().is_one());
166                }
167            }
168        }
169    }
170}
qfall_math/integer/mat_poly_over_z/default.rs

qfall_math/integer/mat_poly_over_z/
default.rs
