qfall_math/integer/
mat_z.rs

1// Copyright © 2023 Marcel Luca Schmidt, Niklas Siemer
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//! `MatZ` is a type of matrix with integer entries of arbitrary length.
10//! This implementation uses the [FLINT](https://flintlib.org/) library.
11
12use crate::utils::parse::partial_string;
13use flint_sys::fmpz_mat::fmpz_mat_struct;
14use std::fmt;
15
16mod arithmetic;
17mod basis_reductions;
18mod cmp;
19mod concat;
20mod default;
21mod determinant;
22mod forms;
23mod from;
24mod get;
25mod inverse;
26mod norm;
27mod ownership;
28mod properties;
29mod sample;
30mod serialize;
31mod set;
32mod sort;
33mod tensor;
34mod to_string;
35mod trace;
36mod transpose;
37mod unsafe_functions;
38mod vector;
39
40/// [`MatZ`] is a matrix with entries of type [`Z`](crate::integer::Z).
41///
42/// Attributes:
43/// - `matrix`: holds [FLINT](https://flintlib.org/)'s [struct](fmpz_mat_struct)
44///   of the [`Z`](crate::integer::Z) matrix
45///
46/// # Examples
47/// ## Matrix usage
48/// ```
49/// use qfall_math::{
50///     integer::{MatZ, Z},
51///     traits::{MatrixGetEntry, MatrixSetEntry},
52/// };
53///
54/// // instantiate new matrix
55/// let id_mat = MatZ::identity(2, 2);
56///
57/// // clone object, set and get entry
58/// let mut clone = id_mat.clone();
59/// clone.set_entry(0, 0, 2);
60/// assert_eq!(clone.get_entry(1, 1).unwrap(), Z::ONE);
61///
62/// // multiplication, transposition and comparison
63/// assert_eq!(id_mat.transpose() * &clone, clone);
64///
65/// // to_string incl. (de-)serialization
66/// assert_eq!("[[1, 0],[0, 1]]", &id_mat.to_string());
67/// assert_eq!(
68///     "{\"matrix\":\"[[1, 0],[0, 1]]\"}",
69///     serde_json::to_string(&id_mat).unwrap()
70/// );
71/// ```
72///
73/// ## Vector usage
74/// ```
75/// use qfall_math::{
76///     integer::{MatZ, Z},
77/// };
78/// use std::str::FromStr;
79///
80/// let row_vec = MatZ::from_str("[[1, 1, 1]]").unwrap();
81/// let col_vec = MatZ::from_str("[[1],[-1],[0]]").unwrap();
82///
83/// // check if matrix instance is vector
84/// assert!(row_vec.is_row_vector());
85/// assert!(col_vec.is_column_vector());
86///
87/// // dot product
88/// assert_eq!(row_vec.dot_product(&col_vec).unwrap(), Z::ZERO);
89///
90/// // norm calculation
91/// assert_eq!(col_vec.norm_eucl_sqrd().unwrap(), Z::from(2));
92/// assert_eq!(row_vec.norm_infty().unwrap(), Z::ONE);
93/// ```
94pub struct MatZ {
95    pub(crate) matrix: fmpz_mat_struct,
96}
97
98impl fmt::Debug for MatZ {
99    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
100        write!(
101            f,
102            "MatZ: {{matrix: {}, storage: {:?}}}",
103            // printing the entire matrix is not meaningful for large matrices
104            partial_string(self, 3, 3),
105            self.matrix
106        )
107    }
108}
qfall_math/integer/mat_z.rs

qfall_math/integer/
mat_z.rs
