qfall_math/rational/
mat_q.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//! [`MatQ`] is a type of matrix with rational entries of arbitrary length.
10//! This implementation uses the [FLINT](https://flintlib.org/) library.
11
12// For **DEVELOPERS**: Many functions assume that the [`MatQ`] instances are reduced.
13// To avoid unnecessary checks and reductions, always return canonical/reduced
14// values. The end-user should be unable to obtain a non-reduced value.
15
16use crate::utils::parse::partial_string;
17use flint_sys::fmpq_mat::fmpq_mat_struct;
18use std::fmt;
19
20mod arithmetic;
21mod cholesky_decomp;
22mod cmp;
23mod concat;
24mod default;
25mod determinant;
26mod from;
27mod get;
28mod gso;
29mod inverse;
30mod norm;
31mod ownership;
32mod properties;
33mod rounding;
34mod sample;
35mod serialize;
36mod set;
37mod sort;
38mod tensor;
39mod to_string;
40mod trace;
41mod transpose;
42mod unsafe_functions;
43mod vector;
44
45/// [`MatQ`] is a matrix with entries of type [`Q`](crate::rational::Q).
46///
47/// Attributes:
48/// - `matrix`: holds [FLINT](https://flintlib.org/)'s [struct](fmpq_mat_struct)
49///   of the [`Q`](crate::rational::Q) matrix
50///
51/// # Examples
52/// ## Matrix usage
53/// ```
54/// use qfall_math::{
55///     rational::{Q, MatQ},
56///     traits::{MatrixGetEntry, MatrixSetEntry},
57/// };
58/// use std::str::FromStr;
59///
60/// // instantiate new matrix
61/// let id_mat = MatQ::from_str("[[1/2, 0/1],[0, 1]]").unwrap();
62///
63/// // clone object, set and get entry
64/// let mut clone = id_mat.clone();
65/// clone.set_entry(0, 0, Q::from(2));
66/// assert_eq!(
67///     clone.get_entry(1, 1).unwrap(),
68///     Q::ONE
69/// );
70///
71/// // to_string
72/// assert_eq!("[[1/2, 0],[0, 1]]", &id_mat.to_string());
73/// ```
74///
75/// ## Vector usage
76/// ```
77/// use qfall_math::{
78///     rational::{Q, MatQ},
79/// };
80/// use std::str::FromStr;
81///
82/// let row_vec = MatQ::from_str("[[1/3, 1/4, 1/5]]").unwrap();
83/// let col_vec = MatQ::from_str("[[-1/-5],[-1],[0]]").unwrap();
84///
85/// // check if matrix instance is vector
86/// assert!(row_vec.is_row_vector());
87/// assert!(col_vec.is_column_vector());
88/// ```
89pub struct MatQ {
90    pub(crate) matrix: fmpq_mat_struct,
91}
92
93impl fmt::Debug for MatQ {
94    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
95        write!(
96            f,
97            "MatQ: {{matrix: {}, storage: {:?}}}",
98            // printing the entire matrix is not meaningful for large matrices
99            partial_string(self, 3, 3),
100            self.matrix
101        )
102    }
103}
qfall_math/rational/mat_q.rs

qfall_math/rational/
mat_q.rs
