Struct MatZ 

pub struct MatZ { /* private fields */ }

MatZ is a matrix with entries of type Z.

Attributes:

• matrix: holds FLINT’s struct of the Z matrix

Examples

Matrix usage

use qfall_math::{
    integer::{MatZ, Z},
    traits::{MatrixGetEntry, MatrixSetEntry},
};

// instantiate new matrix
let id_mat = MatZ::identity(2, 2);

// clone object, set and get entry
let mut clone = id_mat.clone();
clone.set_entry(0, 0, 2);
assert_eq!(clone.get_entry(1, 1).unwrap(), Z::ONE);

// multiplication, transposition and comparison
assert_eq!(id_mat.transpose() * &clone, clone);

// to_string incl. (de-)serialization
assert_eq!("[[1, 0],[0, 1]]", &id_mat.to_string());
assert_eq!(
    "{\"matrix\":\"[[1, 0],[0, 1]]\"}",
    serde_json::to_string(&id_mat).unwrap()
);

Vector usage

use qfall_math::{
    integer::{MatZ, Z},
};
use std::str::FromStr;

let row_vec = MatZ::from_str("[[1, 1, 1]]").unwrap();
let col_vec = MatZ::from_str("[[1],[-1],[0]]").unwrap();

// check if matrix instance is vector
assert!(row_vec.is_row_vector());
assert!(col_vec.is_column_vector());

// dot product
assert_eq!(row_vec.dot_product(&col_vec).unwrap(), Z::ZERO);

// norm calculation
assert_eq!(col_vec.norm_eucl_sqrd().unwrap(), Z::from(2));
assert_eq!(row_vec.norm_infty().unwrap(), Z::ONE);

Implementations

impl MatZ

pub fn add_safe(&self, other: &Self) -> Result<MatZ, MathError>

Implements addition for two MatZ matrices.

Parameters:

• other: specifies the value to add to self

Returns the sum of both matrices as a MatZ or an error if the matrix dimensions mismatch.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let a: MatZ = MatZ::from_str("[[1, 2, 3],[3, 4, 5]]").unwrap();
let b: MatZ = MatZ::from_str("[[1, 9, 3],[1, 0, 5]]").unwrap();

let c: MatZ = a.add_safe(&b).unwrap();

Errors

• Returns a MathError of type MathError::MismatchingMatrixDimension if the matrix dimensions mismatch.

impl MatZ

pub unsafe fn div_exact(self, divisor: impl Into<Z>) -> MatZ

Implements division for a MatZ matrix by a Z integer.

Parameters:

• divisor: specifies the divisor by which the matrix is divided

Returns the quotient of self divided by divisor as a MatZ.

Safety

The divisor MUST exactly divide each element in the matrix. If this is not the case, the result can contain arbitrary values which can depend on the location in memory.

Examples

use qfall_math::integer::{MatZ, Z};
use std::str::FromStr;

let mut mat = MatZ::from_str("[[3, 6],[9, 27]]").unwrap();

let mat_z = unsafe { mat.div_exact(3) };

assert_eq!("[[1, 2],[3, 9]]", mat_z.to_string());

Panics …

• if the divisor is 0.

pub unsafe fn div_exact_ref(&self, divisor: impl Into<Z>) -> MatZ

Implements division for a MatZ matrix by a Z integer.

Parameters:

• divisor: specifies the divisor by which the matrix is divided

Returns the quotient of self divided by divisor as a MatZ.

Safety

The divisor MUST exactly divide each element in the matrix. If this is not the case, the result can contain arbitrary values which can depend on the location in memory.

Examples

use qfall_math::integer::{MatZ, Z};
use std::str::FromStr;

let mat = MatZ::from_str("[[3, 6],[9, 27]]").unwrap();

let mat_z = unsafe { mat.div_exact_ref(3) };

assert_eq!("[[1, 2],[3, 9]]", mat_z.to_string());

Panics …

• if the divisor is 0.

impl MatZ

pub fn mul_safe(&self, other: &Self) -> Result<Self, MathError>

Implements multiplication for two MatZ values.

Parameters:

• other: specifies the value to multiply with self

Returns the product of self and other as a MatZ or an error, if the dimensions of self and other do not match for multiplication.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let a = MatZ::from_str("[[2, 1],[1, 2]]").unwrap();
let b = MatZ::identity(2, 2);

let c: MatZ = a.mul_safe(&b).unwrap();

Errors and Failures

• Returns a MathError of type MathError::MismatchingMatrixDimension if the dimensions of self and other do not match for multiplication.

impl MatZ

pub fn sub_safe(&self, other: &Self) -> Result<MatZ, MathError>

Implements subtraction for two MatZ matrices.

Parameters:

• other: specifies the value to subtract fromself

Returns the result of the subtraction as a MatZ or an error if the matrix dimensions mismatch.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let a: MatZ = MatZ::from_str("[[1, 2, 3],[3, 4, 5]]").unwrap();
let b: MatZ = MatZ::from_str("[[1, 9, 3],[1, 0, 5]]").unwrap();

let c: MatZ = a.sub_safe(&b).unwrap();

Errors

• Returns a MathError of type MathError::MismatchingMatrixDimension if the matrix dimensions mismatch.

impl MatZ

pub fn lll(&self, delta: impl Into<Q>, eta: impl Into<Q>) -> MatZ

Performs the (modified Storjohann) LLL algorithm on the matrix self. This algorithm expects self to be a basis. The reduced matrix is a (δ, η)-reduced basis.

Let the matrix be [b_1, b_2, …, b_n]. Then, it is (δ, η)-LLL-reduced if

• for any i > j, we have |μ_{i,j}| <= η,
• for any i < n, we have δ|b_i*|^2 <= |b_{i+1}* + μ_{i+1,i}b_i*|^2,

where μ_{i,j} =〈b_i, b_j*〉/〈b_j*, b_j*〉and b_i* is the i-th vector of the Gram-Schmidt orthogonalization of our matrix.

Parameters:

• delta: mainly defines the quality of the reduced basis with higher quality the closer it’s chosen to 1. Needs to be chosen between 0.25 < δ <= 1.
• eta: defines the maximum deviation per vector from the Gram-Schmidt orthogonalisation. Needs to be chosen between 0.5 <= η < √δ.

Choosing δ=0.99 and η=0.501 optimizes the quality of the basis and is a good choice to start from. Decreasing δ or increasing η will increase efficiency but decrease the quality of the reduced basis.

Examples

use qfall_math::integer::MatZ;

let mut matrix = MatZ::sample_uniform(2, 2, 0, 65537).unwrap();

let reduced_matrix = matrix.lll(0.75, 0.501);

Panics …

• if δ is not in (0.25, 1].
• if η is not in [0.5, √δ).
• if self can’t be a basis, i.e. #rows < #columns.

pub fn is_reduced(&self, delta: impl Into<Q>, eta: impl Into<Q>) -> bool

Checks if the basis self is (δ, η)-reduced.

Definition of (δ, η)-reduced: Let the matrix be [b_1, b_2, …, b_n]. Then, it is (δ, η)-LLL-reduced if

• for any i > j, we have |μ_{i,j}| <= η,
• for any i < n, we have δ|b_i*|^2 <= |b_{i+1}* + μ_{i+1,i}b_i*|^2,

where μ_{i,j} =〈b_i, b_j*〉/〈b_j*, b_j*〉and b_i* is the i-th vector of the Gram-Schmidt orthogonalization of our matrix.

Parameters:

• delta: mainly defines the quality of the reduced basis with higher quality the closer it’s chosen to 1. If δ > 1, the output will always be false.
• eta: defines the maximum deviation per vector from the Gram-Schmidt orthogonalisation. If η < 0, the output will always be false.

If self has |rows| > |columns|, it can’t be a basis and therefore, the output of this algorithm will always be false.

Returns true if the matrix is a basis that is (δ, η)-reduced. Otherwise, it returns false.

Examples

use qfall_math::integer::MatZ;

let mut matrix = MatZ::sample_uniform(2, 2, 0, 65537).unwrap();
let reduced_matrix = matrix.lll(0.75, 0.501);

let check = reduced_matrix.is_reduced(0.75, 0.501);

assert!(check);

impl MatZ

pub fn new( num_rows: impl TryInto<i64> + Display, num_cols: impl TryInto<i64> + Display, ) -> Self

Creates a new matrix with num_rows rows, num_cols columns and zeros as entries.

Parameters:

• num_rows: number of rows the new matrix should have
• num_cols: number of columns the new matrix should have

Returns a new MatZ instance of the provided dimensions.

Examples

use qfall_math::integer::MatZ;

let matrix = MatZ::new(5, 10);

Panics …

• if the number of rows or columns is negative, 0, or does not fit into an i64.

pub fn identity( num_rows: impl TryInto<i64> + Display, num_cols: impl TryInto<i64> + Display, ) -> Self

Generate a num_rows times num_columns matrix with 1 on the diagonal and 0 anywhere else.

Parameters:

• rum_rows: the number of rows of the identity matrix
• num_columns: the number of columns of the identity matrix

Returns a matrix with 1 across the diagonal and 0 anywhere else.

Examples

use qfall_math::integer::MatZ;

let matrix = MatZ::identity(2, 3);

let identity = MatZ::identity(10, 10);

Panics …

• if the provided number of rows and columns are not suited to create a matrix. For further information see MatZ::new.

impl MatZ

pub fn det(&self) -> Result<Z, MathError>

Returns the determinant of the matrix or an error if the number of rows and columns is not equal.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let matrix = MatZ::from_str("[[1, 2],[3, 4]]").unwrap();

let determinant = matrix.det().unwrap();

Errors and Failures

• Returns a MathError of type MismatchingMatrixDimension if the number of rows and columns is not equal.

impl MatZ

pub fn hermite_nf(&self) -> (MatZ, MatZ)

Computes the Hermite normal form of self along with the transformation matrix U s.t. U * A = H.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;
let matrix = MatZ::from_str("[[1, 2, 12],[2, 4, 5]]").unwrap();
let h_cmp = MatZ::from_str("[[1, 2, 12],[0, 0, 19]]").unwrap();
let u_cmp = MatZ::from_str("[[1, 0],[2, -1]]").unwrap();

let (h, u) = matrix.hermite_nf();

assert_eq!(h_cmp, h);
assert_eq!(u_cmp, u);

pub fn is_in_hermite_nf(&self) -> bool

Checks if self is a matrix in Hermite normal form.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;
let non_hnf = MatZ::from_str("[[1, 2, 12],[2, 4, 5]]").unwrap();
let hnf = MatZ::from_str("[[1, 2, 12],[0, 0, 19]]").unwrap();

assert!(!non_hnf.is_in_hermite_nf());
assert!(hnf.is_in_hermite_nf());

pub fn smith_nf(&self) -> Self

Computes the unique Smith normal form of the matrix self.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;
let matrix = MatZ::from_str("[[1, 2, 12],[2, 4, 5]]").unwrap();
let snf_cmp = MatZ::from_str("[[1, 0, 0],[0, 19, 0]]").unwrap();

let snf = matrix.smith_nf();

assert_eq!(snf_cmp, snf);

pub fn is_in_smith_nf(&self) -> bool

Checks if self is a matrix in Smith normal form.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;
let non_snf = MatZ::from_str("[[1, 2, 12],[2, 4, 5]]").unwrap();
let snf = MatZ::from_str("[[1, 0, 0],[0, 19, 0]]").unwrap();

assert!(!non_snf.is_in_smith_nf());
assert!(snf.is_in_smith_nf());

impl MatZ

pub fn from_utf8( message: &str, num_rows: impl TryInto<i64> + Display, num_cols: impl TryInto<i64> + Display, ) -> Self

Create a MatZ from a String, i.e. its UTF8-Encoding. This function can only construct positive or zero integers, but not negative ones. If the number of bytes and number of entries does not line up, we pad the message with '0's. The inverse of this function is MatZ::to_utf8.

Parameters:

• message: specifies the message that is transformed via its UTF8-Encoding to a new MatZ instance.
• num_rows: number of rows the new matrix should have
• num_cols: number of columns the new matrix should have

Returns a MatZ with corresponding entries to the message’s UTF8-Encoding.

Examples

use qfall_math::integer::MatZ;
let message = "hello!";
  
let matrix = MatZ::from_utf8(&message, 2, 1);

Panics …

• if the provided number of rows and columns are not suited to create a matrix. For further information see MatZ::new.

impl MatZ

pub fn inverse(&self) -> Option<MatQ>

Returns the inverse of the matrix if it exists (is square and has a determinant unequal to 0) and None otherwise.

Examples

use qfall_math::integer::MatZ;
use qfall_math::traits::*;
use std::str::FromStr;

let mut matrix = MatZ::from_str("[[1, 2],[3, 4]]").unwrap();
let matrix_invert = matrix.inverse().unwrap();

impl MatZ

pub fn norm_l_2_infty_sqrd(&self) -> Z

Outputs the squared l_{2, ∞}-norm, i.e. it computes the squared Euclidean norm of each column of the matrix and returns the largest one.

Examples

use qfall_math::integer::{MatZ, Z};
use std::str::FromStr;

let mat = MatZ::from_str("[[2, 3],[2, 0]]").unwrap();

let eucl_norm = mat.norm_l_2_infty_sqrd();

// 3^2 + 0^2 = 9
assert_eq!(Z::from(9), eucl_norm);

pub fn norm_l_2_infty(&self) -> Q

Outputs the l_{2, ∞}-norm, i.e. it computes the Euclidean norm of each column of the matrix and returns the largest one.

Examples

use qfall_math::{integer::MatZ, rational::Q};
use std::str::FromStr;

let mat = MatZ::from_str("[[2, 3],[2, 0]]").unwrap();

let eucl_norm = mat.norm_l_2_infty();

// sqrt(3^2 + 0^2) = 3
assert_eq!(Q::from(3), eucl_norm);

pub fn norm_l_infty_infty(&self) -> Z

Outputs the l_{∞, ∞}-norm, i.e. it computes the ∞-norm of each column of the matrix and returns the largest one.

Examples

use qfall_math::integer::{MatZ, Z};
use std::str::FromStr;

let mat = MatZ::from_str("[[2, 3],[2, 0]]").unwrap();

let eucl_norm = mat.norm_l_infty_infty();

// max{2, 3} = 3
assert_eq!(Z::from(3), eucl_norm);

impl MatZ

pub fn is_identity(&self) -> bool

Checks if a MatZ is the identity matrix.

Returns true if every diagonal entry of the matrix is 1 and every other entry is 0.

Examples

use qfall_math::integer::MatZ;

let value = MatZ::identity(2, 2);
assert!(value.is_identity());

pub fn is_square(&self) -> bool

Checks if a MatZ is a square matrix.

Returns true if the number of rows and columns is identical.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let value = MatZ::from_str("[[4, 0],[0, 1]]").unwrap();
assert!(value.is_square());

pub fn is_zero(&self) -> bool

Checks if every entry of a MatZ is 0.

Returns true if every entry of the matrix is 0.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let value = MatZ::from_str("[[0, 0],[0, 0]]").unwrap();
assert!(value.is_zero());

pub fn is_symmetric(&self) -> bool

Checks if a MatZ is symmetric.

Returns true if we have a_ij == a_ji for all i,j.

Examples

use qfall_math::integer::MatZ;

let value = MatZ::identity(2,2);
assert!(value.is_symmetric());

pub fn rank(&self) -> Z

Returns the rank of the matrix.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let matrix = MatZ::from_str("[[1, 2, 3],[4, 5, 6]]").unwrap();

let rank = matrix.rank();

impl MatZ

pub fn sample_binomial( num_rows: impl TryInto<i64> + Display, num_cols: impl TryInto<i64> + Display, n: impl Into<Z>, p: impl Into<Q>, ) -> Result<Self, MathError>

Outputs a MatZ instance with entries chosen according to the binomial distribution parameterized by n and p.

Parameters:

• num_rows: specifies the number of rows the new matrix should have
• num_cols: specifies the number of columns the new matrix should have
• n: specifies the number of trials
• p: specifies the probability of success

Returns a new MatZ instance with entries chosen according to the binomial distribution or a MathError if n < 0, p ∉ (0,1), n does not fit into an i64, or the dimensions of the matrix were chosen too small.

Examples

use qfall_math::integer::MatZ;

let sample = MatZ::sample_binomial(2, 2, 5, 0.5).unwrap();

Errors and Failures

• Returns a MathError of type InvalidIntegerInput if n < 0.
• Returns a MathError of type InvalidInterval if p ∉ (0,1).
• Returns a MathError of type ConversionError if n does not fit into an i64.

Panics …

• if the provided number of rows and columns are not suited to create a matrix. For further information see MatZ::new.

pub fn sample_binomial_with_offset( num_rows: impl TryInto<i64> + Display, num_cols: impl TryInto<i64> + Display, offset: impl Into<Z>, n: impl Into<Z>, p: impl Into<Q>, ) -> Result<Self, MathError>

Outputs a MatZ instance with entries chosen according to the binomial distribution parameterized by n and p with given offset.

Parameters:

• num_rows: specifies the number of rows the new matrix should have
• num_cols: specifies the number of columns the new matrix should have
• offset: specifies an offset applied to each sample collected from the binomial distribution
• n: specifies the number of trials
• p: specifies the probability of success

Returns a new MatZ instance with entries chosen according to the binomial distribution or a MathError if n < 0, p ∉ (0,1), n does not fit into an i64, or the dimensions of the matrix were chosen too small.

Examples

use qfall_math::integer::MatZ;

let sample = MatZ::sample_binomial_with_offset(2, 2, -1, 2, 0.5).unwrap();

Errors and Failures

• Returns a MathError of type InvalidIntegerInput if n < 0.
• Returns a MathError of type InvalidInterval if p ∉ (0,1).
• Returns a MathError of type ConversionError if n does not fit into an i64.

Panics …

• if the provided number of rows and columns are not suited to create a matrix. For further information see MatZ::new.

impl MatZ

pub fn sample_discrete_gauss( num_rows: impl TryInto<i64> + Display, num_cols: impl TryInto<i64> + Display, center: impl Into<Q>, s: impl Into<Q>, ) -> Result<MatZ, MathError>

Initializes a new matrix with dimensions num_rows x num_columns and with each entry sampled independently according to the discrete Gaussian distribution, using Z::sample_discrete_gauss.

Parameters:

• num_rows: specifies the number of rows the new matrix should have
• num_cols: specifies the number of columns the new matrix should have
• center: specifies the positions of the center with peak probability
• s: specifies the Gaussian parameter, which is proportional to the standard deviation sigma * sqrt(2 * pi) = s

Returns a matrix with each entry sampled independently from the specified discrete Gaussian distribution or an error if s < 0.

Examples

use qfall_math::integer::MatZ;

let sample = MatZ::sample_discrete_gauss(3, 1, 0, 1.25f32).unwrap();

Errors and Failures

• Returns a MathError of type InvalidIntegerInput if s < 0.

Panics …

• if the provided number of rows and columns are not suited to create a matrix. For further information see MatZ::new.

pub fn sample_d( basis: &MatZ, center: &MatQ, s: impl Into<Q>, ) -> Result<Self, MathError>

SampleD samples a discrete Gaussian from the lattice with a provided basis.

We do not check whether basis is actually a basis. Hence, the callee is responsible for making sure that basis provides a suitable basis.

Parameters:

• basis: specifies a basis for the lattice from which is sampled
• n: specifies the range from which Z::sample_discrete_gauss samples
• center: specifies the positions of the center with peak probability
• s: specifies the Gaussian parameter, which is proportional to the standard deviation sigma * sqrt(2 * pi) = s

Returns a lattice vector sampled according to the discrete Gaussian distribution or an error if s < 0, the number of rows of the basis and center differ, or if center is not a column vector.

Examples

use qfall_math::{integer::{MatZ, Z}, rational::{MatQ, Q}};
let basis = MatZ::identity(5, 5);
let center = MatQ::new(5, 1);

let sample = MatZ::sample_d(&basis, &center, 1.25f32).unwrap();

Errors and Failures

• Returns a MathError of type InvalidIntegerInput if s < 0.
• Returns a MathError of type MismatchingMatrixDimension if the number of rows of the basis and center differ.
• Returns a MathError of type StringConversionError if center is not a column vector.

This function implements SampleD according to:

• [1] Gentry, Craig and Peikert, Chris and Vaikuntanathan, Vinod (2008). Trapdoors for hard lattices and new cryptographic constructions. In: Proceedings of the fortieth annual ACM symposium on Theory of computing. https://dl.acm.org/doi/pdf/10.1145/1374376.1374407

pub fn sample_d_common_non_spherical( sigma_sqrt: &MatQ, r: impl Into<Q>, ) -> Result<Self, MathError>

Samples a non-spherical discrete Gaussian depending on your choice of sigma_sqrt using the standard basis and center 0.

Parameters:

• sigma_sqrt: specifies the positive definite Gaussian covariance matrix with which the intermediate continuous Gaussian is sampled before the randomized rounding is applied. Here sigma_sqrt = sqrt(sigma^2 - r^2*I) where sigma is the target covariance matrix. The root can be computed using the MatQ::cholesky_decomposition.
• r: specifies the rounding parameter for MatQ::randomized_rounding.

Returns a lattice vector sampled according to the discrete Gaussian distribution.

Examples

use qfall_math::integer::MatZ;
use qfall_math::rational::{Q, MatQ};
use std::str::FromStr;
use crate::qfall_math::traits::Pow;

let covariance_matrix = MatQ::from_str("[[100,1],[1,17]]").unwrap();
let r = Q::from(4);

let sigma_sqrt = covariance_matrix - r.pow(2).unwrap() * MatQ::identity(2, 2);

let sample = MatZ::sample_d_common_non_spherical(&sigma_sqrt.cholesky_decomposition(), r).unwrap();

Errors and Failures

• Returns a MathError of type InvalidIntegerInput if the r < 0.
• Returns a MathError of type NoSquareMatrix if the matrix is not symmetric.

This function implements SampleD according to Algorithm 1. in [2].

• [2] Peikert, Chris. “An efficient and parallel Gaussian sampler for lattices. In Annual Cryptology Conference, pp. 80-97. Berlin, Heidelberg: Springer Berlin Heidelberg, 2010. https://link.springer.com/chapter/10.1007/978-3-642-14623-7_5

pub fn sample_d_precomputed_gso( basis: &MatZ, basis_gso: &MatQ, center: &MatQ, s: impl Into<Q>, ) -> Result<Self, MathError>

SampleD samples a discrete Gaussian from the lattice with a provided basis.

We do not check whether basis is actually a basis or whether basis_gso is actually the gso of basis. Hence, the callee is responsible for making sure that basis provides a suitable basis and basis_gso is a corresponding GSO.

Parameters:

• basis: specifies a basis for the lattice from which is sampled
• basis_gso: specifies the precomputed gso for basis
• center: specifies the positions of the center with peak probability
• s: specifies the Gaussian parameter, which is proportional to the standard deviation sigma * sqrt(2 * pi) = s

Returns a lattice vector sampled according to the discrete Gaussian distribution or an error if s < 0, the number of rows of the basis and center differ, or if center is not a column vector.

Examples

use qfall_math::{integer::{MatZ, Z}, rational::{MatQ, Q}};
let basis = MatZ::identity(5, 5);
let center = MatQ::new(5, 1);
let basis_gso = MatQ::from(&basis).gso();

let sample = MatZ::sample_d_precomputed_gso(&basis, &basis_gso, &center, 1.25f32).unwrap();

Errors and Failures

• Returns a MathError of type InvalidIntegerInput if s < 0.
• Returns a MathError of type MismatchingMatrixDimension if the number of rows of the basis and center differ.
• Returns a MathError of type StringConversionError if center is not a column vector.

Panics …

• if the number of rows/columns of basis_gso and basis mismatch.

This function implements SampleD according to:

• [1] Gentry, Craig and Peikert, Chris and Vaikuntanathan, Vinod (2008). Trapdoors for hard lattices and new cryptographic constructions. In: Proceedings of the fortieth annual ACM symposium on Theory of computing. https://dl.acm.org/doi/pdf/10.1145/1374376.1374407

impl MatZ

pub fn sample_uniform( num_rows: impl TryInto<i64> + Display, num_cols: impl TryInto<i64> + Display, lower_bound: impl Into<Z>, upper_bound: impl Into<Z>, ) -> Result<Self, MathError>

Outputs a MatZ instance with entries chosen uniform at random in [lower_bound, upper_bound).

The internally used uniform at random chosen bytes are generated by ThreadRng, which uses ChaCha12 and is considered cryptographically secure.

Parameters:

• num_rows: specifies the number of rows the new matrix should have
• num_cols: specifies the number of columns the new matrix should have
• lower_bound: specifies the included lower bound of the interval over which is sampled
• upper_bound: specifies the excluded upper bound of the interval over which is sampled

Returns a new MatZ instance with entries chosen uniformly at random in [lower_bound, upper_bound) or a MathError if the dimensions of the matrix or the interval were chosen too small.

Examples

use qfall_math::integer::MatZ;

let matrix = MatZ::sample_uniform(3, 3, 17, 26).unwrap();

Errors and Failures

• Returns a MathError of type InvalidInterval if the given upper_bound isn’t at least larger than lower_bound.

Panics …

• if the provided number of rows and columns are not suited to create a matrix. For further information see MatZ::new.

impl MatZ

pub fn reverse_columns(&mut self)

Swaps the i-th column with the n-i-th column for all i <= n/2 of the specified matrix with n columns.

Examples

use qfall_math::integer::MatZ;

let mut matrix = MatZ::new(4, 3);
matrix.reverse_columns();

pub fn reverse_rows(&mut self)

Swaps the i-th row with the n-i-th row for all i <= n/2 of the specified matrix with n rows.

Examples

use qfall_math::integer::MatZ;

let mut matrix = MatZ::new(4, 3);
matrix.reverse_rows();

impl MatZ

pub fn sort_by_column<T: Ord>( &self, cond_func: fn(&Self) -> Result<T, MathError>, ) -> Result<Self, MathError>

Sorts the columns of the matrix based on some condition defined by cond_func in an ascending order.

This condition is usually a norm with the described input-output behaviour.

Parameters:

• cond_func: computes values implementing Ord over the columns of the specified matrix. These values are then used to re-order / sort the rows of the matrix.

Returns an empty Ok if the action could be performed successfully. A MathError is returned if the execution of cond_func returned an error.

Examples

Use a build-in function as condition

use qfall_math::integer::MatZ;
use std::str::FromStr;
let mat = MatZ::from_str("[[3, 2, 1]]").unwrap();
let cmp = MatZ::from_str("[[1, 2, 3]]").unwrap();

let sorted = mat.sort_by_column(MatZ::norm_eucl_sqrd).unwrap();

assert_eq!(cmp, sorted);

Use a custom function as condition

This function needs to take a column vector as input and output a type implementing PartialOrd

use qfall_math::{integer::{MatZ, Z}, error::MathError, traits::{MatrixDimensions, MatrixGetEntry}};
use std::str::FromStr;
let mat = MatZ::from_str("[[3, 2, 1]]").unwrap();
let cmp = MatZ::from_str("[[1, 2, 3]]").unwrap();

fn custom_cond_func(matrix: &MatZ) -> Result<Z, MathError> {
    let mut sum = Z::ZERO;
    for entry in matrix.get_entries_rowwise() {
        sum += entry;
    }
    Ok(sum)
}

let sorted = mat.sort_by_column(custom_cond_func).unwrap();

assert_eq!(cmp, sorted);

Errors and Failures

• Returns a MathError of the same type as cond_func if the execution of cond_func fails.

pub fn sort_by_row<T: Ord>( &self, cond_func: fn(&Self) -> Result<T, MathError>, ) -> Result<Self, MathError>

Sorts the rows of the matrix based on some condition defined by cond_func in an ascending order.

This condition is usually a norm with the described input-output behaviour.

Parameters:

• cond_func: computes values implementing Ord over the columns of the specified matrix. These values are then used to re-order / sort the columns of the matrix.

Returns an empty Ok if the action could be performed successfully. A MathError is returned if the execution of cond_func returned an error.

Examples

Use a build-in function as condition

use qfall_math::integer::MatZ;
use std::str::FromStr;
let mat = MatZ::from_str("[[3],[2],[1]]").unwrap();
let cmp = MatZ::from_str("[[1],[2],[3]]").unwrap();

let sorted = mat.sort_by_row(MatZ::norm_infty).unwrap();

assert_eq!(cmp, sorted);

Use a custom function as condition

This function needs to take a row vector as input and output a type implementing PartialOrd

use qfall_math::{integer::{MatZ, Z}, error::MathError, traits::{MatrixDimensions, MatrixGetEntry}};
use std::str::FromStr;
let mat = MatZ::from_str("[[3],[2],[1]]").unwrap();
let cmp = MatZ::from_str("[[1],[2],[3]]").unwrap();

fn custom_cond_func(matrix: &MatZ) -> Result<Z, MathError> {
    let mut sum = Z::ZERO;
    for entry in matrix.get_entries_columnwise() {
        sum += entry;
    }
    Ok(sum)
}

let sorted = mat.sort_by_row(custom_cond_func).unwrap();

assert_eq!(cmp, sorted);

Errors and Failures

• Returns a MathError of the same type as cond_func if the execution of cond_func fails.

impl MatZ

pub fn to_utf8(&self) -> Result<String, FromUtf8Error>

Enables conversion to a UTF8-Encoded String for MatZ values. Every entry is padded with 00s s.t. all entries contain the same number of bytes. Afterwards, they are appended row-by-row and converted. The inverse to this function is MatZ::from_utf8 for valid UTF8-Encodings.

Warning: Not every byte-sequence forms a valid UTF8-Encoding. In these cases, an error is returned. Please check the format of your message again. The matrix entries are evaluated row by row, i.e. in the order of the output of mat_z.to_string().

Returns the corresponding UTF8-encoded String or a FromUtf8Error if the byte sequence contains an invalid UTF8-character.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;
let matrix = MatZ::from_str("[[104, 101, 108],[108, 111, 33]]").unwrap();

let message = matrix.to_utf8().unwrap();

assert_eq!("hello!", message);

Errors and Failures

• Returns a FromUtf8Error if the integer’s byte sequence contains invalid UTF8-characters.

impl MatZ

pub fn pretty_string( &self, nr_printed_rows: u64, nr_printed_columns: u64, ) -> String

Outputs the matrix as a String, where the upper leftmost nr_printed_rows x nr_printed_columns submatrix is output entirely as well as the corresponding entries in the last column and row of the matrix.

Parameters:

• nr_printed_rows: defines the number of rows of the upper leftmost matrix that are printed entirely
• nr_printed_columns: defines the number of columns of the upper leftmost matrix that are printed entirely

Returns a String representing the abbreviated matrix.

Example

use qfall_math::integer::MatZ;
let matrix = MatZ::identity(10, 10);

println!("Matrix: {}", matrix.pretty_string(2, 2));
// outputs the following:
// Matrix: [
//   [1, 0, , ..., 0],
//   [0, 1, , ..., 0],
//   [...],
//   [0, 0, , ..., 1]
// ]

impl MatZ

pub fn trace(&self) -> Result<Z, MathError>

Returns the trace of a matrix and an error, if the matrix is not square.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let matrix = MatZ::from_str("[[1, 2],[3, 4]]").unwrap();
let trace = matrix.trace().unwrap();

Errors and Failures

• Returns a MathError of type NoSquareMatrix if the matrix is not a square matrix

impl MatZ

pub fn transpose(&self) -> Self

Returns the transposed form of the given matrix, i.e. rows get transformed to columns and vice versa.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let mat = MatZ::from_str("[[2, 1],[2, 1],[2, 1]]").unwrap();
let cmp = MatZ::from_str("[[2, 2, 2],[1, 1, 1]]").unwrap();

assert_eq!(mat.transpose(), cmp);

impl MatZ

pub unsafe fn get_fmpz_mat_struct(&mut self) -> &mut fmpz_mat_struct

Returns a mutable reference to the field matrix of type fmpz_mat_struct.

WARNING: The returned struct is part of flint_sys. Any changes to this object are unsafe and may introduce memory leaks.

This function is a passthrough to enable users of this library to use flint_sys and with that FLINT functions that might not be covered in our library yet. If this is the case, please consider contributing to this open-source project by opening a Pull Request at qfall_math to provide this feature in the future.

Safety

Any flint_sys struct and function is part of a FFI to the C-library FLINT. As FLINT is a C-library, it does not provide all memory safety features that Rust and our Wrapper provide. Thus, using functions of flint_sys can introduce memory leaks.

impl MatZ

pub unsafe fn set_fmpz_mat_struct(&mut self, flint_struct: fmpz_mat_struct)

Sets the field matrix of type fmpz_mat_struct to flint_struct.

Parameters:

• flint_struct: value to set the attribute to

This function is a passthrough to enable users of this library to use flint_sys and with that FLINT functions that might not be covered in our library yet. If this is the case, please consider contributing to this open-source project by opening a Pull Request at qfall_math to provide this feature in the future.

Safety

Ensure that the old struct does not share any memory with any other structs that might be used in the future. The memory of the old struct is freed using this function.

Any flint_sys struct and function is part of a FFI to the C-library FLINT. As FLINT is a C-library, it does not provide all memory safety features that Rust and our Wrapper provide. Thus, using functions of flint_sys can introduce memory leaks.

impl MatZ

pub fn dot_product(&self, other: &Self) -> Result<Z, MathError>

Returns the dot product of two vectors of type MatZ.

Parameters:

• other: specifies the other vector the dot product is calculated over

Returns the resulting dot_product as a Z or an error if the given MatZ instances aren’t vectors or have different numbers of entries.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let vec_1 = MatZ::from_str("[[1],[2],[3]]").unwrap();
let vec_2 = MatZ::from_str("[[1, 3, 2]]").unwrap();

let dot_prod = vec_1.dot_product(&vec_2).unwrap();

// 1*1 + 2*3 + 3*2 = 13
assert_eq!(Z::from(13), dot_prod);

Errors and Failures

• Returns a MathError of type MathError::VectorFunctionCalledOnNonVector if the given MatZ instance is not a (row or column) vector.
• Returns a MathError of type MathError::MismatchingMatrixDimension if the given vectors have different lengths.

impl MatZ

pub fn is_row_vector(&self) -> bool

Returns true if the provided MatZ has only one row, i.e. is a row vector. Otherwise, returns false.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let vec = MatZ::from_str("[[1, 2, 3]]").unwrap();

assert!(vec.is_row_vector());
assert!(!vec.transpose().is_row_vector());

pub fn is_column_vector(&self) -> bool

Returns true if the provided MatZ has only one column, i.e. is a column vector. Otherwise, returns false.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let vec = MatZ::from_str("[[1],[2],[3]]").unwrap();

assert!(vec.is_column_vector());
assert!(!vec.transpose().is_column_vector());

pub fn is_vector(&self) -> bool

Returns true if the provided MatZ has only one column or one row, i.e. is a vector. Otherwise, returns false.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let vec = MatZ::from_str("[[1],[2],[3]]").unwrap();

assert!(vec.is_vector());
assert!(vec.transpose().is_vector());

pub fn has_single_entry(&self) -> bool

Returns true if the provided MatZ has only one entry, i.e. is a 1x1 matrix. Otherwise, returns false.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let vec = MatZ::from_str("[[1]]").unwrap();

assert!(vec.has_single_entry());

impl MatZ

pub fn norm_eucl_sqrd(&self) -> Result<Z, MathError>

Returns the squared Euclidean norm or squared 2-norm of the given (row or column) vector or an error if the given MatZ instance is not a (row or column) vector.

Examples

use qfall_math::integer::{MatZ, Z};
use std::str::FromStr;

let vec = MatZ::from_str("[[1],[2],[3]]").unwrap();

let sqrd_2_norm = vec.norm_eucl_sqrd().unwrap();

// 1*1 + 2*2 + 3*3 = 14
assert_eq!(Z::from(14), sqrd_2_norm);

Errors and Failures

• Returns a MathError of type MathError::VectorFunctionCalledOnNonVector if the given MatZ instance is not a (row or column) vector.

pub fn norm_eucl(&self) -> Result<Q, MathError>

Returns the Euclidean norm or 2-norm of the given (row or column) vector or an error if the given MatZ instance is not a (row or column) vector.

Examples

use qfall_math::{integer::MatZ, rational::Q};
use std::str::FromStr;

let vec = MatZ::from_str("[[2],[2],[2],[2]]").unwrap();

let eucl_norm = vec.norm_eucl().unwrap();

// sqrt(4 * 2^2) = 4
assert_eq!(Q::from(4), eucl_norm);

Errors and Failures

• Returns a MathError of type MathError::VectorFunctionCalledOnNonVector if the given MatZ instance is not a (row or column) vector.

pub fn norm_infty(&self) -> Result<Z, MathError>

Returns the infinity norm or ∞-norm of the given (row or column) vector or an error if the given MatZ instance is not a (row or column) vector.

Examples

use qfall_math::integer::{MatZ, Z};
use std::str::FromStr;

let vec = MatZ::from_str("[[1],[2],[3]]").unwrap();

let infty_norm = vec.norm_infty().unwrap();

// max{1, 2, 3} = 3
assert_eq!(Z::from(3), infty_norm);

Errors and Failures

• Returns a MathError of type MathError::VectorFunctionCalledOnNonVector if the given MatZ instance is not a (row or column) vector.

Trait Implementations

impl Add<&MatZ> for &MatQ

fn add(self, other: &MatZ) -> Self::Output

Implements the Add trait for two MatQ values. Add is implemented for any combination of MatQ and MatZ.

Parameters:

• other: specifies the value to add to self

Returns the sum of both numbers as a MatQ.

Examples

use qfall_math::{rational::MatQ, integer::MatZ};
use std::str::FromStr;

let a = MatQ::from_str("[[1/2, 2/3, 3/4],[3/4, 4/5, 5/7]]").unwrap();
let b = MatZ::identity(2, 3);

let d: MatQ = &a + &b;
let e: MatQ = a + &b;
let f: MatQ = &b + d;
let g: MatQ = b + f;

Panics …

• if the dimensions of both matrices mismatch.

type Output = MatQ

The resulting type after applying the + operator.

impl Add<&MatZ> for &MatZq

fn add(self, other: &MatZ) -> Self::Output

Implements the Add trait for a MatZ and a MatZq matrix. Add is implemented for any combination of MatZ and MatZq and vice versa.

Parameters:

• other: specifies the value to add to self

Returns the sum of both numbers as a MatZq.

Examples

use qfall_math::{integer::MatZ, integer_mod_q::MatZq};
use std::str::FromStr;

let a = MatZ::from_str("[[1, 2, 3],[3, 4, 5]]").unwrap();
let b = MatZq::from_str("[[1, 9, 3],[1, 0, 5]] mod 7").unwrap();

let c = &a + &b;
let d = a.clone() + b.clone();
let e = &b + &a;
let f = b + a;

Panics …

• if the dimensions of both matrices mismatch.

type Output = MatZq

The resulting type after applying the + operator.

impl Add for &MatZ

fn add(self, other: Self) -> Self::Output

Implements the Add trait for two MatZ values. Add is implemented for any combination of MatZ and borrowed MatZ.

Parameters:

• other: specifies the value to add to self

Returns the sum of both numbers as a MatZ.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let a: MatZ = MatZ::from_str("[[1, 2, 3],[3, 4, 5]]").unwrap();
let b: MatZ = MatZ::from_str("[[1, 9, 3],[1, 0, 5]]").unwrap();

let c: MatZ = &a + &b;
let d: MatZ = a + b;
let e: MatZ = &c + d;
let f: MatZ = c + &e;

Panics …

• if the dimensions of both matrices mismatch.

type Output = MatZ

The resulting type after applying the + operator.

impl AddAssign<&MatZ> for MatQ

fn add_assign(&mut self, other: &MatZ)

Documentation at MatQ::add_assign.

impl AddAssign<&MatZ> for MatZ

fn add_assign(&mut self, other: &Self)

Computes the addition of self and other reusing the memory of self.

Parameters:

• other: specifies the value to add to self

Examples

use qfall_math::integer::MatZ;
let mut a = MatZ::identity(2, 2);
let b = MatZ::new(2, 2);

a += &b;
a += b;

Panics …

• if the matrix dimensions mismatch.

impl AddAssign<&MatZ> for MatZq

fn add_assign(&mut self, other: &MatZ)

Documentation at MatZq::add_assign.

impl AddAssign<MatZ> for MatQ

fn add_assign(&mut self, other: MatZ)

Documentation at MatQ::add_assign.

impl AddAssign<MatZ> for MatZq

fn add_assign(&mut self, other: MatZ)

Documentation at MatZq::add_assign.

impl AddAssign for MatZ

fn add_assign(&mut self, other: MatZ)

Documentation at MatZ::add_assign.

impl Clone for MatZ

fn clone(&self) -> Self

Clones the given element and returns a deep clone of the MatZ element.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let str_1 = "[[1, 2, 3],[3, 4, 5]]";
let a = MatZ::from_str(str_1).unwrap();
let b = a.clone();

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl CompareBase<&MatZ> for MatNTTPolynomialRingZq

fn compare_base(&self, other: &T) -> bool

Compares the base elements of the objects and returns true if they match and an operation between the two provided types is possible.

fn call_compare_base_error(&self, other: &T) -> Option<MathError>

Calls an error that gives small explanation how the base elements differ. This function only calls the error and does not check if the two actually differ.

impl CompareBase<&MatZ> for MatPolyOverZ

fn compare_base(&self, other: &T) -> bool

Compares the base elements of the objects and returns true if they match and an operation between the two provided types is possible.

fn call_compare_base_error(&self, other: &T) -> Option<MathError>

Calls an error that gives small explanation how the base elements differ. This function only calls the error and does not check if the two actually differ.

impl CompareBase<&MatZ> for MatPolynomialRingZq

fn compare_base(&self, other: &T) -> bool

Compares the base elements of the objects and returns true if they match and an operation between the two provided types is possible.

fn call_compare_base_error(&self, other: &T) -> Option<MathError>

Calls an error that gives small explanation how the base elements differ. This function only calls the error and does not check if the two actually differ.

impl CompareBase<&MatZ> for MatQ

fn compare_base(&self, other: &T) -> bool

Compares the base elements of the objects and returns true if they match and an operation between the two provided types is possible.

fn call_compare_base_error(&self, other: &T) -> Option<MathError>

Calls an error that gives small explanation how the base elements differ. This function only calls the error and does not check if the two actually differ.

impl CompareBase<&MatZ> for MatZ

fn compare_base(&self, other: &T) -> bool

Compares the base elements of the objects and returns true if they match and an operation between the two provided types is possible.

fn call_compare_base_error(&self, other: &T) -> Option<MathError>

Calls an error that gives small explanation how the base elements differ. This function only calls the error and does not check if the two actually differ.

impl CompareBase<&MatZ> for MatZq

fn compare_base(&self, other: &T) -> bool

Compares the base elements of the objects and returns true if they match and an operation between the two provided types is possible.

fn call_compare_base_error(&self, other: &T) -> Option<MathError>

Calls an error that gives small explanation how the base elements differ. This function only calls the error and does not check if the two actually differ.

impl<Integer: Into<Z>> CompareBase<Integer> for MatZ

fn compare_base(&self, other: &T) -> bool

Compares the base elements of the objects and returns true if they match and an operation between the two provided types is possible.

fn call_compare_base_error(&self, other: &T) -> Option<MathError>

Calls an error that gives small explanation how the base elements differ. This function only calls the error and does not check if the two actually differ.

impl CompareBase<MatZ> for MatNTTPolynomialRingZq

fn compare_base(&self, other: &T) -> bool

Compares the base elements of the objects and returns true if they match and an operation between the two provided types is possible.

fn call_compare_base_error(&self, other: &T) -> Option<MathError>

Calls an error that gives small explanation how the base elements differ. This function only calls the error and does not check if the two actually differ.

impl CompareBase<MatZ> for MatPolyOverZ

fn compare_base(&self, other: &T) -> bool

Compares the base elements of the objects and returns true if they match and an operation between the two provided types is possible.

fn call_compare_base_error(&self, other: &T) -> Option<MathError>

Calls an error that gives small explanation how the base elements differ. This function only calls the error and does not check if the two actually differ.

impl CompareBase<MatZ> for MatPolynomialRingZq

fn compare_base(&self, other: &T) -> bool

Compares the base elements of the objects and returns true if they match and an operation between the two provided types is possible.

fn call_compare_base_error(&self, other: &T) -> Option<MathError>

Calls an error that gives small explanation how the base elements differ. This function only calls the error and does not check if the two actually differ.

impl CompareBase<MatZ> for MatQ

fn compare_base(&self, other: &T) -> bool

Compares the base elements of the objects and returns true if they match and an operation between the two provided types is possible.

fn call_compare_base_error(&self, other: &T) -> Option<MathError>

Calls an error that gives small explanation how the base elements differ. This function only calls the error and does not check if the two actually differ.

impl CompareBase<MatZ> for MatZq

fn compare_base(&self, other: &T) -> bool

Compares the base elements of the objects and returns true if they match and an operation between the two provided types is possible.

fn call_compare_base_error(&self, other: &T) -> Option<MathError>

Calls an error that gives small explanation how the base elements differ. This function only calls the error and does not check if the two actually differ.

impl CompareBase for MatZ

fn compare_base(&self, other: &T) -> bool

Compares the base elements of the objects and returns true if they match and an operation between the two provided types is possible.

fn call_compare_base_error(&self, other: &T) -> Option<MathError>

Calls an error that gives small explanation how the base elements differ. This function only calls the error and does not check if the two actually differ.

impl Concatenate for &MatZ

fn concat_vertical(self, other: Self) -> Result<Self::Output, MathError>

Concatenates self with other vertically, i.e. other is added below.

Parameters:

• other: the other matrix to concatenate with self

Returns a vertical concatenation of the two matrices or a an error, if the matrices can not be concatenated vertically.

Examples

use qfall_math::traits::*;
use qfall_math::integer::MatZ;

let mat_1 = MatZ::new(13, 5);
let mat_2 = MatZ::new(17, 5);

let mat_vert = mat_1.concat_vertical(&mat_2).unwrap();

Errors and Failures

• Returns a MathError of type MismatchingMatrixDimension if the matrices can not be concatenated due to mismatching dimensions

fn concat_horizontal(self, other: Self) -> Result<Self::Output, MathError>

Concatenates self with other horizontally, i.e. other is added on the right.

Parameters:

• other: the other matrix to concatenate with self

Returns a horizontal concatenation of the two matrices or a an error, if the matrices can not be concatenated horizontally.

Examples

use qfall_math::traits::*;
use qfall_math::integer::MatZ;

let mat_1 = MatZ::new(17, 5);
let mat_2 = MatZ::new(17, 6);

let mat_vert = mat_1.concat_horizontal(&mat_2).unwrap();

Errors and Failures

• Returns a MathError of type MismatchingMatrixDimension if the matrices can not be concatenated due to mismatching dimensions

type Output = MatZ

impl Debug for MatZ

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for MatZ

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Implements the deserialize option. This allows to create a MatZ from a given Json-object.

impl Display for MatZ

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Allows to convert a matrix of type MatZ into a String.

Returns the Matrix in form of a String. For matrix [[1, 2, 3],[4, 5, 6]] the String looks like this [[1, 2, 3],[4, 5, 6]].

Examples

use qfall_math::integer::MatZ;
use core::fmt;
use std::str::FromStr;

let matrix = MatZ::from_str("[[1, 2, 3],[4, 5, 6]]").unwrap();
println!("{matrix}");

use qfall_math::integer::MatZ;
use core::fmt;
use std::str::FromStr;

let matrix = MatZ::from_str("[[1, 2, 3],[4, 5, 6]]").unwrap();
let matrix_string = matrix.to_string();

impl Div<&Z> for &MatZ

fn div(self, divisor: &Z) -> Self::Output

Implements the Div trait for a MatZ matrix by a Z integer. Div is also implemented for borrowed values.

Parameters:

• divisor: specifies the divisor by which the matrix is divided

Returns the quotient of self divided by divisor as a MatQ.

Examples

use qfall_math::integer::{MatZ, Z};
use std::str::FromStr;

let mat = MatZ::from_str("[[3, 5],[9, 22]]").unwrap();
let divisor = Z::from(3);

let mat_q = &mat / &divisor;

assert_eq!("[[1, 5/3],[3, 22/3]]", mat_q.to_string());

Panics …

• if the divisor is 0.

type Output = MatQ

The resulting type after applying the / operator.

impl Drop for MatZ

fn drop(&mut self)

Drops the given MatZ value and frees the allocated memory.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let str_1 = "[[1, 2, 3],[3, 4, 5]]";
{
    let a = MatZ::from_str(str_1).unwrap();
} // as a's scope ends here, it get's dropped

use qfall_math::integer::MatZ;
use std::str::FromStr;

let str_1 = "[[1, 2, 3],[3, 4, 5]]";
let a = MatZ::from_str(str_1).unwrap();
drop(a); // explicitly drops a's value

impl<Integer: Into<Z>> Evaluate<Integer, MatZ> for MatPolyOverZ

fn evaluate(&self, value: Integer) -> MatZ

Evaluates a MatPolyOverZ on a given input entrywise.

Parameters:

• value: the value with which to evaluate the matrix of polynomials.

Returns the evaluation of the polynomial as a MatZ.

Examples

use qfall_math::traits::*;
use qfall_math::integer::Z;
use qfall_math::integer::MatPolyOverZ;
use std::str::FromStr;

let poly = MatPolyOverZ::from_str("[[0, 1  17, 2  24 42],[2  24 42, 2  24 42, 2  24 42]]").unwrap();
let res = poly.evaluate(3);

impl From<&MatZ> for MatPolyOverZ

fn from(matrix: &MatZ) -> Self

Creates a MatPolyOverZ with constant polynomials defined by a MatZ.

Parameters

• matrix: a matrix with constant integers.

Returns a matrix of polynomial that all have the first coefficient set to the value in the matrix.

Examples

use qfall_math::integer::{MatZ, MatPolyOverZ};

let mat_z = MatZ::identity(10, 10);
let mat_poly = MatPolyOverZ::from(&mat_z);

impl From<&MatZ> for MatQ

fn from(matrix: &MatZ) -> Self

Creates a MatQ from a MatZ.

Parameters:

• matrix: the matrix from which the entries are taken

Returns a new MatQ matrix with entries from the MatZ instance.

Examples

use qfall_math::integer::MatZ;
use qfall_math::rational::MatQ;
use std::str::FromStr;

let m = MatZ::from_str("[[1, 2],[3, -1]]").unwrap();

let a = MatQ::from(&m);

impl From<&MatZ> for MatZ

fn from(value: &MatZ) -> Self

Alias for MatZ::clone.

impl From<&MatZ> for String

fn from(value: &MatZ) -> Self

Converts a MatZ into its String representation.

Parameters:

• value: specifies the matrix that will be represented as a String

Returns a String of the form "[[row_0],[row_1],...[row_n]]".

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;
let matrix = MatZ::from_str("[[6, 1],[5, 2]]").unwrap();

let string: String = matrix.into();

impl From<MatZ> for MatPolyOverZ

fn from(value: MatZ) -> Self

Documentation can be found at MatPolyOverZ::from for &MatZ.

impl From<MatZ> for MatQ

fn from(value: MatZ) -> Self

Documentation can be found at MatQ::from for &MatZ.

impl From<MatZ> for String

fn from(value: MatZ) -> Self

Documentation can be found at String::from for &MatZ.

impl FromCoefficientEmbedding<&MatZ> for PolyOverZ

fn from_coefficient_embedding(embedding: &MatZ) -> Self

Computes a polynomial from a vector. The first i-th entry of the column vector is taken as the coefficient of the polynomial. It inverts the operation of PolyOverZ::into_coefficient_embedding.

Parameters:

• embedding: the column vector that encodes the embedding

Returns a polynomial that corresponds to the embedding.

Examples

use std::str::FromStr;
use qfall_math::{
    integer::{MatZ, PolyOverZ},
    traits::FromCoefficientEmbedding,
};

let vector = MatZ::from_str("[[17],[3],[-5]]").unwrap();
let poly = PolyOverZ::from_coefficient_embedding(&vector);
let cmp_poly = PolyOverZ::from_str("3  17 3 -5").unwrap();
assert_eq!(cmp_poly, poly);

Panics …

• if the provided embedding is not a column vector.

impl FromStr for MatZ

fn from_str(string: &str) -> Result<Self, MathError>

Creates a MatZ matrix with entries in Z from a String.

Parameters:

• string: the matrix of form: "[[1, 2, 3],[4, 5, 6]]" for a 2x3 matrix with entries 1, 2, 3 in the first row and 4, 5, 6 in the second row.

Returns a MatZ or an error if the matrix is not formatted in a suitable way, the number of rows or columns is too large (must fit into i64), the number of entries in rows is unequal or if an entry is not formatted correctly.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let string = String::from("[[1, 2, 3],[3, 4, 5]]");
let matrix = MatZ::from_str(&string).unwrap();

Errors and Failures

• Returns a MathError of type StringConversionError
  • if the matrix is not formatted in a suitable way,
  • if the number of rows or columns is too large (must fit into i64),
  • if the number of entries in rows is unequal, or
  • if an entry is not formatted correctly. For further information see Z::from_str.

Panics …

• if the provided number of rows and columns are not suited to create a matrix. For further information see MatZ::new.

type Err = MathError

The associated error which can be returned from parsing.

impl IntoCoefficientEmbedding<MatZ> for &MatPolyOverZ

fn into_coefficient_embedding(self, size: impl Into<i64>) -> MatZ

Computes the coefficient embedding of the matrix of polynomials in a MatZ. Each column vector of polynomials is embedded into size many row vectors of coefficients. The first one containing their coefficients of degree 0, and the last one their coefficients of degree size - 1. It inverts the operation of MatPolyOverZ::from_coefficient_embedding.

Parameters:

• size: determines the number of rows of the embedding. It has to be larger than the degree of the polynomial.

Returns a coefficient embedding as a matrix if size is large enough.

Examples

use std::str::FromStr;
use qfall_math::{
    integer::{MatZ, MatPolyOverZ},
    traits::IntoCoefficientEmbedding,
};

let poly = MatPolyOverZ::from_str("[[1  1, 2  1 2],[1  -1, 2  -1 -2]]").unwrap();
let embedding = poly.into_coefficient_embedding(2);
let cmp_mat = MatZ::from_str("[[1, 1],[0, 2],[-1, -1],[0, -2]]").unwrap();
assert_eq!(cmp_mat, embedding);

Panics …

• if size is not larger than the degree of the polynomial, i.e. not all coefficients can be embedded.

impl IntoCoefficientEmbedding<MatZ> for &PolyOverZ

fn into_coefficient_embedding(self, size: impl Into<i64>) -> MatZ

Computes the coefficient embedding of the polynomial in a MatZ as a column vector, where the i-th entry of the vector corresponds to the i-th coefficient. It inverts the operation of PolyOverZ::from_coefficient_embedding.

Parameters:

• size: determines the number of rows of the embedding. It has to be larger than the degree of the polynomial.

Returns a coefficient embedding as a column vector if size is large enough.

Examples

use std::str::FromStr;
use qfall_math::{
    integer::{MatZ, PolyOverZ},
    traits::IntoCoefficientEmbedding,
};

let poly = PolyOverZ::from_str("3  17 3 -5").unwrap();
let vector = poly.into_coefficient_embedding(4);
let cmp_vector = MatZ::from_str("[[17],[3],[-5],[0]]").unwrap();
assert_eq!(cmp_vector, vector);

Panics …

• if size is not larger than the degree of the polynomial, i.e. not all coefficients can be embedded.

impl MatrixDimensions for MatZ

fn get_num_rows(&self) -> i64

Returns the number of rows of the matrix as a i64.

Examples

use qfall_math::integer::MatZ;
use qfall_math::traits::*;

let matrix = MatZ::new(5, 6);
let rows = matrix.get_num_rows();

fn get_num_columns(&self) -> i64

Returns the number of columns of the matrix as a i64.

Examples

use qfall_math::integer::MatZ;
use qfall_math::traits::*;

let matrix = MatZ::new(5, 6);
let columns = matrix.get_num_columns();

impl MatrixGetEntry<Z> for MatZ

unsafe fn get_entry_unchecked(&self, row: i64, column: i64) -> Z

Outputs the Z value of a specific matrix entry without checking whether it’s part of the matrix.

Parameters:

• row: specifies the row in which the entry is located
• column: specifies the column in which the entry is located

Returns the Z value of the matrix at the position of the given row and column.

Safety

To use this function safely, make sure that the selected entry is part of the matrix. If it is not, memory leaks, unexpected panics, etc. might occur.

Examples

use qfall_math::integer::{MatZ, Z};
use qfall_math::traits::MatrixGetEntry;
use std::str::FromStr;

let matrix = MatZ::from_str("[[1, 2, 3],[4, 5, 6],[7, 8, 9]]").unwrap();

assert_eq!(unsafe { matrix.get_entry_unchecked(0, 2) }, Z::from(3));
assert_eq!(unsafe { matrix.get_entry_unchecked(2, 1) }, Z::from(8));
assert_eq!(unsafe { matrix.get_entry_unchecked(2, 1) }, Z::from(8));

fn get_entry( &self, row: impl TryInto<i64> + Display, column: impl TryInto<i64> + Display, ) -> Result<T, MathError>

Returns the value of a specific matrix entry.

fn get_entries(&self) -> Vec<Vec<T>>

Outputs a Vec<Vec<T>> containing all entries of the matrix s.t. any entry in row i and column j can be accessed via entries[i][j] if entries = matrix.get_entries.

fn get_entries_rowwise(&self) -> Vec<T>

Outputs a Vec<T> containing all entries of the matrix in a row-wise order, i.e. a matrix [[2, 3, 4],[5, 6, 7]] can be accessed via this function in this order [2, 3, 4, 5, 6, 7].

fn get_entries_columnwise(&self) -> Vec<T>

Outputs a Vec<T> containing all entries of the matrix in a column-wise order, i.e. a matrix [[2, 3, 4],[5, 6, 7]] can be accessed via this function in this order [2, 5, 3, 6, 4, 7].

impl MatrixGetSubmatrix for MatZ

unsafe fn get_submatrix_unchecked( &self, row_1: i64, row_2: i64, col_1: i64, col_2: i64, ) -> Self

Returns a deep copy of the submatrix defined by the given parameters and does not check the provided dimensions. There is also a safe version of this function that checks the input.

Parameters: row_1: the starting row of the submatrix row_2: the ending row of the submatrix col_1: the starting column of the submatrix col_2: the ending column of the submatrix

Returns the submatrix from (row_1, col_1) to (row_2, col_2)(exclusively).

Examples

use qfall_math::{integer::MatZ, traits::MatrixGetSubmatrix};
use std::str::FromStr;

let mat = MatZ::identity(3, 3);

let sub_mat_1 = mat.get_submatrix(0, 2, 1, 1).unwrap();
let sub_mat_2 = mat.get_submatrix(0, -1, 1, -2).unwrap();
let sub_mat_3 = unsafe{mat.get_submatrix_unchecked(0, 3, 1, 2)};

let e_2 = MatZ::from_str("[[0],[1],[0]]").unwrap();
assert_eq!(e_2, sub_mat_1);
assert_eq!(e_2, sub_mat_2);
assert_eq!(e_2, sub_mat_3);

Safety

To use this function safely, make sure that the selected submatrix is part of the matrix. If it is not, memory leaks, unexpected panics, etc. might occur.

fn get_row( &self, row: impl TryInto<i64> + Display + Clone, ) -> Result<Self, MathError>

Outputs the row vector of the specified row.

unsafe fn get_row_unchecked(&self, row: i64) -> Self

Outputs the row vector of the specified row.

fn get_column( &self, column: impl TryInto<i64> + Display + Clone, ) -> Result<Self, MathError>

Outputs the column vector of the specified column.

unsafe fn get_column_unchecked(&self, column: i64) -> Self

Outputs the column vector of the specified column.

fn get_submatrix( &self, row_1: impl TryInto<i64> + Display, row_2: impl TryInto<i64> + Display, col_1: impl TryInto<i64> + Display, col_2: impl TryInto<i64> + Display, ) -> Result<Self, MathError>

Returns a deep copy of the submatrix defined by the given parameters. All entries starting from (row_1, col_1) to (row_2, col_2)(inclusively) are collected in a new matrix. Note that row_1 >= row_2 and col_1 >= col_2 must hold after converting negative indices. Otherwise the function will panic.

fn get_rows(&self) -> Vec<Self>

Outputs a Vec containing all rows of the matrix in order. Use this function for simple iteration over the rows of the matrix.

fn get_columns(&self) -> Vec<Self>

Outputs a Vec containing all columns of the matrix in order. Use this function for simple iteration over the columns of the matrix.

impl<Integer: Into<Z>> MatrixSetEntry<Integer> for MatZ

unsafe fn set_entry_unchecked(&mut self, row: i64, column: i64, value: Integer)

Sets the value of a specific matrix entry according to the provided value without checking whether the coordinate is part of the matrix.

Parameters:

• row: specifies the row in which the entry is located
• column: specifies the column in which the entry is located
• value: specifies the value to which the entry is set

Safety

To use this function safely, make sure that the selected entry is part of the matrix. If it is not, memory leaks, unexpected panics, etc. might occur.

Examples

use qfall_math::integer::{MatZ, Z};
use qfall_math::traits::MatrixSetEntry;

let mut matrix = MatZ::new(3, 3);

unsafe {
    matrix.set_entry_unchecked(0, 1, 5);
    matrix.set_entry_unchecked(2, 2, 9);
}

assert_eq!("[[0, 5, 0],[0, 0, 0],[0, 0, 9]]", matrix.to_string());

fn set_entry( &mut self, row: impl TryInto<i64> + Display, column: impl TryInto<i64> + Display, value: T, ) -> Result<(), MathError>

Sets the value of a specific matrix entry according to a given value.

impl MatrixSetSubmatrix for MatZ

unsafe fn set_submatrix_unchecked( &mut self, row_self_start: i64, col_self_start: i64, row_self_end: i64, col_self_end: i64, other: &Self, row_other_start: i64, col_other_start: i64, row_other_end: i64, col_other_end: i64, )

Sets the matrix entries in self to entries defined in other. The entries in self starting from (row_self_start, col_self_start) up to (row_self_end, col_self_end)are set to be the entries from the submatrix from other defined by (row_other_start, col_other_start) to (row_other_end, col_other_end) (exclusively).

Parameters: row_self_start: the starting row of the matrix in which to set a submatrix col_self_start: the starting column of the matrix in which to set a submatrix other: the matrix from where to take the submatrix to set row_other_start: the starting row of the specified submatrix col_other_start: the starting column of the specified submatrix row_other_end: the ending row of the specified submatrix col_other_end:the ending column of the specified submatrix

Examples

use qfall_math::{integer::MatZ, traits::MatrixSetSubmatrix};
use std::str::FromStr;

let mut mat = MatZ::identity(3, 3);

mat.set_submatrix(0, 1, &mat.clone(), 0, 0, 1, 1).unwrap();
// [[1,1,0],[0,0,1],[0,0,1]]
let mat_cmp = MatZ::from_str("[[1, 1, 0],[0, 0, 1],[0, 0, 1]]").unwrap();
assert_eq!(mat, mat_cmp);

unsafe{ mat.set_submatrix_unchecked(2, 0, 3, 2, &mat.clone(), 0, 0, 1, 2) };
let mat_cmp = MatZ::from_str("[[1, 1, 0],[0, 0, 1],[1, 1, 1]]").unwrap();
assert_eq!(mat, mat_cmp);

Safety

To use this function safely, make sure that the selected submatrices are part of the matrices, the submatrices are of the same dimensions and the base types are the same. If not, memory leaks, unexpected panics, etc. might occur.

fn set_row( &mut self, row_0: impl TryInto<i64> + Display, other: &Self, row_1: impl TryInto<i64> + Display, ) -> Result<(), MathError>

Sets a row of the given matrix to the provided row of other.

unsafe fn set_row_unchecked(&mut self, row_0: i64, other: &Self, row_1: i64)

Sets a row of the given matrix to the provided row of other.

fn set_column( &mut self, col_0: impl TryInto<i64> + Display, other: &Self, col_1: impl TryInto<i64> + Display, ) -> Result<(), MathError>

Sets a column of the given matrix to the provided column of other.

unsafe fn set_column_unchecked(&mut self, col_0: i64, other: &Self, col_1: i64)

Sets a column of the given matrix to the provided column of other.

fn set_submatrix( &mut self, row_self_start: impl TryInto<i64> + Display, col_self_start: impl TryInto<i64> + Display, other: &Self, row_other_start: impl TryInto<i64> + Display, col_other_start: impl TryInto<i64> + Display, row_other_end: impl TryInto<i64> + Display, col_other_end: impl TryInto<i64> + Display, ) -> Result<(), MathError>

Sets the matrix entries in self to entries defined in other. The entries in self starting from (row_self_start, col_self_start) are set to be the entries from the submatrix from other defined by (row_other_start, col_other_start) to (row_other_end, col_other_end) (inclusively). The original matrix must have sufficiently many entries to contain the defined submatrix.

impl MatrixSwaps for MatZ

fn swap_entries( &mut self, row_0: impl TryInto<i64> + Display, col_0: impl TryInto<i64> + Display, row_1: impl TryInto<i64> + Display, col_1: impl TryInto<i64> + Display, ) -> Result<(), MathError>

Swaps two entries of the specified matrix.

Parameters:

• row_0: specifies the row, in which the first entry is located
• col_0: specifies the column, in which the first entry is located
• row_1: specifies the row, in which the second entry is located
• col_1: specifies the column, in which the second entry is located

Negative indices can be used to index from the back, e.g., -1 for the last element.

Returns an empty Ok if the action could be performed successfully. Otherwise, a MathError is returned if one of the specified entries is not part of the matrix.

Examples

use qfall_math::{integer::MatZ, traits::MatrixSwaps};

let mut matrix = MatZ::new(4, 3);
matrix.swap_entries(0, 0, 2, 1);

Errors and Failures

• Returns a MathError of type MathError::OutOfBounds if row or column are greater than the matrix size.

fn swap_columns( &mut self, col_0: impl TryInto<i64> + Display, col_1: impl TryInto<i64> + Display, ) -> Result<(), MathError>

Swaps two columns of the specified matrix.

Parameters:

• col_0: specifies the first column which is swapped with the second one
• col_1: specifies the second column which is swapped with the first one

Negative indices can be used to index from the back, e.g., -1 for the last element.

Returns an empty Ok if the action could be performed successfully. Otherwise, a MathError is returned if one of the specified columns is not part of the matrix.

Examples

use qfall_math::{integer::MatZ, traits::MatrixSwaps};

let mut matrix = MatZ::new(4, 3);
matrix.swap_columns(0, 2);

Errors and Failures

• Returns a MathError of type OutOfBounds if one of the given columns is greater than the matrix.

fn swap_rows( &mut self, row_0: impl TryInto<i64> + Display, row_1: impl TryInto<i64> + Display, ) -> Result<(), MathError>

Swaps two rows of the specified matrix.

Parameters:

• row_0: specifies the first row which is swapped with the second one
• row_1: specifies the second row which is swapped with the first one

Negative indices can be used to index from the back, e.g., -1 for the last element.

Returns an empty Ok if the action could be performed successfully. Otherwise, a MathError is returned if one of the specified rows is not part of the matrix.

Examples

use qfall_math::{integer::MatZ, traits::MatrixSwaps};

let mut matrix = MatZ::new(4, 3);
matrix.swap_rows(0, 2);

Errors and Failures

• Returns a MathError of type OutOfBounds if one of the given rows is greater than the matrix.

impl Mul<&MatQ> for &MatZ

fn mul(self, other: &MatQ) -> Self::Output

Implements the Mul trait for MatZ and MatQ. Mul is implemented for any combination of owned and borrowed values.

Parameters:

• other: specifies the value to multiply with self

Returns the product of self and other as a MatQ.

Examples

use qfall_math::integer::MatZ;
use qfall_math::rational::MatQ;
use std::str::FromStr;

let a = MatZ::identity(2, 2);
let b = MatQ::from_str("[[2/3, 1/2],[8/4, 7]]").unwrap();


let c = &a * &b;
let d = a * b;
let e = &MatZ::identity(2, 2) * c;
let f = MatZ::identity(2, 2) * &e;

Panics …

• if the dimensions of self and other do not match for multiplication.

type Output = MatQ

The resulting type after applying the * operator.

impl Mul<&MatZ> for &MatQ

fn mul(self, other: &MatZ) -> Self::Output

Implements the Mul trait for MatQ and MatZ. Mul is implemented for any combination of owned and borrowed values.

Parameters:

• other: specifies the value to multiply with self

Returns the product of self and other as a MatQ.

Examples

use qfall_math::integer::MatZ;
use qfall_math::rational::MatQ;
use std::str::FromStr;

let a = MatQ::from_str("[[2/3, 1/2],[8/4, 7]]").unwrap();
let b = MatZ::identity(2, 2);

let c = &a * &b;
let d = a * b;
let e = c * &MatZ::identity(2, 2);
let f = &e * MatZ::identity(2, 2);

Panics …

• if the dimensions of self and other do not match for multiplication.

type Output = MatQ

The resulting type after applying the * operator.

impl Mul<&MatZ> for &MatZq

fn mul(self, other: &MatZ) -> Self::Output

Implements the Mul trait for MatZq and MatZ. Mul is implemented for any combination of owned and borrowed values.

Parameters:

• other: specifies the value to multiply with self

Returns the product of self and other as a MatZq.

Examples

use qfall_math::integer_mod_q::MatZq;
use qfall_math::integer::MatZ;
use std::str::FromStr;

let a = MatZq::from_str("[[2, 1],[1, 2]] mod 3").unwrap();
let b = MatZ::identity(2, 2);

let c = &a * &b;
let d = a * b;
let e = d * &MatZ::identity(2, 2);
let f = &e * MatZ::identity(2, 2);

Panics …

• if the dimensions of self and other do not match for multiplication.

type Output = MatZq

The resulting type after applying the * operator.

impl Mul<&MatZq> for &MatZ

fn mul(self, other: &MatZq) -> Self::Output

Implements the Mul trait for MatZ and MatZq. Mul is implemented for any combination of owned and borrowed values.

Parameters:

• other: specifies the value to multiply with self

Returns the product of self and other as a MatZq.

Examples

use qfall_math::integer_mod_q::MatZq;
use qfall_math::integer::MatZ;
use std::str::FromStr;

let a = MatZ::identity(2, 2);
let b = MatZq::from_str("[[2, 1],[1, 2]] mod 3").unwrap();

let c = &a * &b;
let d = a * b;
let e = &MatZ::identity(2, 2) * d;
let f = MatZ::identity(2, 2) * &e;

Panics …

• if the dimensions of self and other do not match for multiplication.

type Output = MatZq

The resulting type after applying the * operator.

impl Mul<&Q> for &MatZ

fn mul(self, scalar: &Q) -> Self::Output

Implements the Mul trait for a MatZ matrix with a Q rational. Mul is implemented for any combination of owned and borrowed values.

Parameters:

• scalar: specifies the scalar by which the matrix is multiplied

Returns the product of self and scalar as a MatQ.

Examples

use qfall_math::integer::MatZ;
use qfall_math::rational::Q;
use std::str::FromStr;

let mat_1 = MatZ::from_str("[[2, 1],[1, 2]]").unwrap();
let rational = Q::from((1,3));

let mat_2 = &mat_1 * &rational;

type Output = MatQ

The resulting type after applying the * operator.

impl Mul<&Z> for &MatZ

fn mul(self, scalar: &Z) -> Self::Output

Implements the Mul trait for a MatZ matrix with a Z integer. Mul is implemented for any combination of owned and borrowed values.

Parameters:

• scalar: specifies the scalar by which the matrix is multiplied

Returns the product of self and scalar as a MatZ.

Examples

use qfall_math::integer::MatZ;
use qfall_math::integer::Z;
use std::str::FromStr;

let mat_1 = MatZ::from_str("[[2, 1],[1, 2]]").unwrap();
let integer = Z::from(3);

let mat_2 = &mat_1 * &integer;

type Output = MatZ

The resulting type after applying the * operator.

impl Mul<&Zq> for &MatZ

fn mul(self, scalar: &Zq) -> Self::Output

Implements the Mul trait for a MatZ matrix with a Zq representative of a residue class. Mul is implemented for any combination of owned and borrowed values.

Parameters:

• scalar: specifies the scalar by which the matrix is multiplied

Returns the product of self and scalar as a MatZq.

Examples

use qfall_math::integer::MatZ;
use qfall_math::integer_mod_q::Zq;
use std::str::FromStr;

let mat_1 = MatZ::from_str("[[2, 1],[1, 2]]").unwrap();
let zq = Zq::from((1,3));

let mat_2 = &mat_1 * &zq;

type Output = MatZq

The resulting type after applying the * operator.

impl Mul for &MatZ

fn mul(self, other: Self) -> Self::Output

Implements the Mul trait for two MatZ values. Mul is implemented for any combination of MatZ and borrowed MatZ.

Parameters:

• other: specifies the value to multiply with self

Returns the product of self and other as a MatZ.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let a = MatZ::from_str("[[2, 1],[1, 2]]").unwrap();
let b = MatZ::identity(2, 2);

let c = &a * &b;
let d = a * b;
let e = &c * d;
let f = c * &e;

Panics …

• if the dimensions of self and other do not match for multiplication.

type Output = MatZ

The resulting type after applying the * operator.

impl MulAssign<&Z> for MatZ

fn mul_assign(&mut self, scalar: &Z)

Computes the scalar multiplication of self and scalar reusing the memory of self.

Parameters:

• scalar: specifies the value to multiply to self

Returns the scalar of the matrix as a MatZ.

Examples

use qfall_math::integer::{Z,MatZ};
use std::str::FromStr;

let mut a = MatZ::from_str("[[2, 1],[1, 2]]").unwrap();
let b = Z::from(2);

a *= &b;
a *= b;
a *= 2;
a *= -2;

impl MulAssign<Z> for MatZ

fn mul_assign(&mut self, other: Z)

Documentation at MatZ::mul_assign.

impl MulAssign<i16> for MatZ

fn mul_assign(&mut self, other: i16)

Documentation at MatZ::mul_assign.

impl MulAssign<i32> for MatZ

fn mul_assign(&mut self, other: i32)

Documentation at MatZ::mul_assign.

impl MulAssign<i64> for MatZ

fn mul_assign(&mut self, scalar: i64)

Documentation at MatZ::mul_assign.

impl MulAssign<i8> for MatZ

fn mul_assign(&mut self, other: i8)

Documentation at MatZ::mul_assign.

impl MulAssign<u16> for MatZ

fn mul_assign(&mut self, other: u16)

Documentation at MatZ::mul_assign.

impl MulAssign<u32> for MatZ

fn mul_assign(&mut self, other: u32)

Documentation at MatZ::mul_assign.

impl MulAssign<u64> for MatZ

fn mul_assign(&mut self, scalar: u64)

Documentation at MatZ::mul_assign.

impl MulAssign<u8> for MatZ

fn mul_assign(&mut self, other: u8)

Documentation at MatZ::mul_assign.

impl PartialEq<MatZ> for MatQ

fn eq(&self, other: &MatZ) -> bool

Checks if an integer matrix and a rational matrix are equal. Used by the == and != operators. PartialEq is also implemented for MatZ using MatQ.

Parameters:

• other: the other value that is used to compare the elements

Returns true if the elements are equal, otherwise false.

Examples

use qfall_math::integer::MatZ;
use qfall_math::rational::MatQ;
use std::str::FromStr;
let a: MatQ = MatQ::from_str("[[42, 2],[3, 4]]").unwrap();
let b: MatZ = MatZ::from_str("[[42, 2],[3, 4]]").unwrap();

// These are all equivalent and return true.
let compared: bool = (a == b);
let compared: bool = (b == a);
let compared: bool = (&a == &b);
let compared: bool = (&b == &a);
let compared: bool = (a.eq(&b));
let compared: bool = (b.eq(&a));
let compared: bool = (MatQ::eq(&a, &b));
let compared: bool = (MatZ::eq(&b, &a));

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl PartialEq for MatZ

fn eq(&self, other: &Self) -> bool

Checks if two MatZ instances are equal. Used by the == and != operators.

Parameters:

• other: the other value that is compare against self

Returns true if the elements are equal, otherwise false.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let a = MatZ::from_str("[[1, 2],[3, 4]]").unwrap();
let b = MatZ::from_str("[[1, 2],[2, 4]]").unwrap();

// These are all equivalent and return false.
let compared: bool = (a == b);
let compared: bool = (&a == &b);
let compared: bool = (a.eq(&b));
let compared: bool = (MatZ::eq(&a, &b));

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Rem<&Modulus> for &MatZ

fn rem(self, modulus: &Modulus) -> Self::Output

Computes self mod modulus. For negative entries in self, the smallest positive representative is returned.

Parameters:

• modulus: specifies a non-zero integer over which the positive remainders are computed

Returns self mod modulus as a MatZ instance.

Examples

use qfall_math::integer::MatZ;
use qfall_math::integer_mod_q::Modulus;
use std::str::FromStr;

let a: MatZ = MatZ::from_str("[[-2],[42]]").unwrap();
let b = Modulus::from(24);

let c: MatZ = &a % &b;

type Output = MatZ

The resulting type after applying the % operator.

impl Rem<&Z> for &MatZ

fn rem(self, modulus: &Z) -> Self::Output

Computes self mod modulus as long as modulus is greater than 1. For negative entries in self, the smallest positive representative is returned.

Parameters:

• modulus: specifies a non-zero integer over which the positive remainders are computed

Returns self mod modulus as a MatZ instance.

Examples

use qfall_math::integer::{MatZ, Z};
use std::str::FromStr;

let a: MatZ = MatZ::from_str("[[-2],[42]]").unwrap();
let b: Z = Z::from(24);

let c: MatZ = a % b;

Panics …

• if modulus is smaller than 2.

type Output = MatZ

The resulting type after applying the % operator.

impl Rem<i16> for MatZ

fn rem(self, modulus: i16) -> Self::Output

Documentation can be found at MatZ::rem.

type Output = MatZ

The resulting type after applying the % operator.

impl Rem<i32> for MatZ

fn rem(self, modulus: i32) -> Self::Output

Documentation can be found at MatZ::rem.

type Output = MatZ

The resulting type after applying the % operator.

impl Rem<i64> for MatZ

fn rem(self, modulus: i64) -> Self::Output

Documentation can be found at MatZ::rem.

type Output = MatZ

The resulting type after applying the % operator.

impl Rem<i8> for MatZ

fn rem(self, modulus: i8) -> Self::Output

Documentation can be found at MatZ::rem.

type Output = MatZ

The resulting type after applying the % operator.

impl Rem<u16> for MatZ

fn rem(self, modulus: u16) -> Self::Output

Documentation can be found at MatZ::rem.

type Output = MatZ

The resulting type after applying the % operator.

impl Rem<u32> for MatZ

fn rem(self, modulus: u32) -> Self::Output

Documentation can be found at MatZ::rem.

type Output = MatZ

The resulting type after applying the % operator.

impl Rem<u64> for MatZ

fn rem(self, modulus: u64) -> Self::Output

Documentation can be found at MatZ::rem.

type Output = MatZ

The resulting type after applying the % operator.

impl Rem<u8> for MatZ

fn rem(self, modulus: u8) -> Self::Output

Documentation can be found at MatZ::rem.

type Output = MatZ

The resulting type after applying the % operator.

impl Serialize for MatZ

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Implements the serialize option. This allows to create a Json-object from a given MatZ.

impl Sub<&MatQ> for &MatZ

fn sub(self, other: &MatQ) -> Self::Output

Implements the Sub trait for a MatZ and a MatQ matrix. Sub is implemented for any combination of owned and borrowed values.

Parameters:

• other: specifies the matrix to subtract from self.

Returns the subtraction of self and other as a MatQ.

Examples

use qfall_math::{integer::MatZ, rational::MatQ};
use std::str::FromStr;

let a = MatQ::from_str("[[1/2, 9, 3/8],[1/7, 0, 5]]").unwrap();
let b = MatZ::from_str("[[1, 2, 3],[3, 4, 5]]").unwrap();

let c = &b - &a;
let d = b.clone() - a.clone();
let e = &b - &a;
let f = b - a;

Panics …

• if the dimensions of both matrices mismatch.

type Output = MatQ

The resulting type after applying the - operator.

impl Sub<&MatZ> for &MatQ

fn sub(self, other: &MatZ) -> Self::Output

Implements the Sub trait for a MatQ and a MatZ matrix. Sub is implemented for any combination of owned and borrowed values.

Parameters:

• other: specifies the matrix to subtract from self.

Returns the subtraction of self and other as a MatQ.

Examples

use qfall_math::{integer::MatZ, rational::MatQ};
use std::str::FromStr;

let a = MatZ::from_str("[[1, 2, 3],[3, 4, 5]]").unwrap();
let b = MatQ::from_str("[[1/2, 9, 3/8],[1/7, 0, 5]]").unwrap();

let c = &b - &a;
let d = b.clone() - a.clone();
let e = &b - &a;
let f = b - a;

Panics …

• if the dimensions of both matrices mismatch.

type Output = MatQ

The resulting type after applying the - operator.

impl Sub<&MatZ> for &MatZq

fn sub(self, other: &MatZ) -> Self::Output

Implements the Sub trait for a MatZq and a MatZ matrix. Sub is implemented for any combination of owned and borrowed values.

Parameters:

• other: specifies the matrix to subtract from self.

Returns the subtraction of self and other as a MatZq.

Examples

use qfall_math::{integer::MatZ, integer_mod_q::MatZq};
use std::str::FromStr;

let a = MatZ::from_str("[[1, 2, 3],[3, 4, 5]]").unwrap();
let b = MatZq::from_str("[[1, 9, 3],[1, 0, 5]] mod 7").unwrap();

let c = &b - &a;
let d = b.clone() - a.clone();
let e = &b - &a;
let f = b - a;

Panics …

• if the dimensions of both matrices mismatch.

type Output = MatZq

The resulting type after applying the - operator.

impl Sub<&MatZq> for &MatZ

fn sub(self, other: &MatZq) -> Self::Output

Implements the Sub trait for a MatZ and a MatZq matrix. Sub is implemented for any combination of owned and borrowed values.

Parameters:

• other: specifies the matrix to subtract from self.

Returns the subtraction of self and other as a MatZq.

Examples

use qfall_math::{integer::MatZ, integer_mod_q::MatZq};
use std::str::FromStr;

let a = MatZ::from_str("[[1, 2, 3],[3, 4, 5]]").unwrap();
let b = MatZq::from_str("[[1, 9, 3],[1, 0, 5]] mod 7").unwrap();

let c = &a - &b;
let d = a.clone() - b.clone();
let e = &a - &b;
let f = a - b;

Panics …

• if the dimensions of both matrices mismatch.

type Output = MatZq

The resulting type after applying the - operator.

impl Sub for &MatZ

fn sub(self, other: Self) -> Self::Output

Implements the Sub trait for two MatZ values. Sub is implemented for any combination of MatZ and borrowed MatZ.

Parameters:

• other: specifies the value to subtract fromself

Returns the result of the subtraction as a MatZ.

Examples

use qfall_math::integer::MatZ;
use std::str::FromStr;

let a: MatZ = MatZ::from_str("[[1, 2, 3],[3, 4, 5]]").unwrap();
let b: MatZ = MatZ::from_str("[[1, 9, 3],[1, 0, 5]]").unwrap();

let c: MatZ = &a - &b;
let d: MatZ = a - b;
let e: MatZ = &c - d;
let f: MatZ = c - &e;

Panics …

• if the dimensions of both matrices mismatch.

type Output = MatZ

The resulting type after applying the - operator.

impl SubAssign<&MatZ> for MatQ

fn sub_assign(&mut self, other: &MatZ)

Documentation at MatQ::sub_assign.

impl SubAssign<&MatZ> for MatZ

fn sub_assign(&mut self, other: &Self)

Computes the subtraction of self and other reusing the memory of self.

Parameters:

• other: specifies the value to subtract from self

Examples

use qfall_math::integer::MatZ;
let mut a = MatZ::identity(2, 2);
let b = MatZ::new(2, 2);

a -= &b;
a -= b;

Panics …

• if the matrix dimensions mismatch.

impl SubAssign<&MatZ> for MatZq

fn sub_assign(&mut self, other: &MatZ)

Documentation at MatZq::sub_assign.

impl SubAssign<MatZ> for MatQ

fn sub_assign(&mut self, other: MatZ)

Documentation at MatQ::sub_assign.

impl SubAssign<MatZ> for MatZq

fn sub_assign(&mut self, other: MatZ)

Documentation at MatZq::sub_assign.

impl SubAssign for MatZ

fn sub_assign(&mut self, other: MatZ)

Documentation at MatZ::sub_assign.

impl Tensor for MatZ

fn tensor_product(&self, other: &Self) -> Self

Computes the tensor product of self with other.

Parameters:

• other: the value with which the tensor product is computed.

Returns the tensor product of self with other.

Examples

use qfall_math::integer::MatZ;
use qfall_math::traits::Tensor;
use std::str::FromStr;

let mat_1 = MatZ::from_str("[[1, 1],[2, 2]]").unwrap();
let mat_2 = MatZ::from_str("[[1, 2],[3, 4]]").unwrap();

let mat_ab = mat_1.tensor_product(&mat_2);
let mat_ba = mat_2.tensor_product(&mat_1);

let res_ab = "[[1, 2, 1, 2],[3, 4, 3, 4],[2, 4, 2, 4],[6, 8, 6, 8]]";
let res_ba = "[[1, 1, 2, 2],[2, 2, 4, 4],[3, 3, 4, 4],[6, 6, 8, 8]]";
assert_eq!(mat_ab, MatZ::from_str(res_ab).unwrap());
assert_eq!(mat_ba, MatZ::from_str(res_ba).unwrap());

impl Eq for MatZ