Struct MatQ 

pub struct MatQ { /* private fields */ }

MatQ is a matrix with entries of type Q.

Attributes:

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

Examples

Matrix usage

use qfall_math::{
    rational::{Q, MatQ},
    traits::{MatrixGetEntry, MatrixSetEntry},
};
use std::str::FromStr;

// instantiate new matrix
let id_mat = MatQ::from_str("[[1/2, 0/1],[0, 1]]").unwrap();

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

// to_string
assert_eq!("[[1/2, 0],[0, 1]]", &id_mat.to_string());

Vector usage

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

let row_vec = MatQ::from_str("[[1/3, 1/4, 1/5]]").unwrap();
let col_vec = MatQ::from_str("[[-1/-5],[-1],[0]]").unwrap();

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

Implementations

impl MatQ

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

Implements addition for two MatQ matrices.

Parameters:

• other: specifies the value to add to self

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

Examples

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

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

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

Errors

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

impl MatQ

pub fn mul_f64_unchecked(&self, other: &Self) -> MatQ

Multiplies the matrices self and other naively with each other using their f64 presentation, i.e. with a small loss of precision.

This function can speed up multiplications of MatQ’s as it allows for some loss of precision. The loss of precision depends on the size of the matrices and how exact the entries could be represented by a f64.

WARNING: This function is less efficient than Mul for integer values or entries with small numerators and denominators. This function becomes more efficient once self or other has entries with large numerators and denominators as FLINT’s implementation does not allow any loss of precision.

WARNING: Please be aware that the deviation of the representation of the matrices’ entries as f64 will scale with the size of the entries, e.g. an entry within the size of 2^{64} might deviate from the original value by a distance of 1_000. This loss of precision might be aggravated by this matrix multiplication with a factor of self.get_num_columns() for each entry in the resulting matrix.

WARNING: This function is unchecked, i.e. the user is expected to align matrix dimensions for multiplication.

Example

use qfall_math::integer::MatZ;
let mat = MatZ::sample_uniform(3, 3, -256, 256).unwrap().inverse().unwrap();

let mat_inv_sqrd = mat.mul_f64_unchecked(&mat);

Panics …

• if the dimensions of self and other do not match for multiplication.
• if any result during the naive computation of matrix multiplication is larger than f64::MAX or smaller than f64::MIN.

impl MatQ

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

Implements multiplication for two MatQ values.

Parameters:

• other: specifies the value to multiply with self

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

Examples

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

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

let c: MatQ = 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 MatQ

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

Implements subtraction for two MatQ matrices.

Parameters:

• other: specifies the value to subtract fromself

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

Examples

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

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

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

Errors

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

impl MatQ

pub fn cholesky_decomposition(&self) -> MatQ

This function performs the Cholesky decomposition (the Cholesky algorithm) and produces a matrix L such that self = L * L^T. This function relies on the precision of Q::sqrt and will not provide perfect results in all cases. Furthermore, the Cholesky decomposition requires a Hermitian positive-definite matrix.

Returns the Cholesky decomposition of a Hermitian positive-definite matrix.

Examples

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

let matrix = MatQ::from_str("[[4, 12, -16],[12,37,-43],[-16,-43,98]]").unwrap();

let l = matrix.cholesky_decomposition();
assert_eq!(matrix, &l * l.transpose());

Panics …

• if self is not a symmetric matrix,
• if self has eigenvalues smaller than 0.

pub fn cholesky_decomposition_flint(&self) -> MatQ

This function implements the Cholesky decomposition according to FLINTs implementation. As FLINTs algorithm is not (yet) accessible through flint-sys, this implementation follows the implementation of the algorithm from FLINT. This, however, also means that we will work with less precision as we will work with conversions to f64 and not use Q. In turn, this makes the function much more efficient, but not applicable to large numbers.

This function relies on the precision of f64::sqrt and will not provide perfect results in all cases. Furthermore, the Cholesky decomposition requires a Hermitian positive-definite matrix.

Returns the Cholesky decomposition of a Hermitian positive-definite matrix.

Examples

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

let matrix = MatQ::from_str("[[4, 12, -16],[12,37,-43],[-16,-43,98]]").unwrap();

let l = matrix.cholesky_decomposition_flint();
assert_eq!(matrix, &l * l.transpose());

Panics …

• if self is not a symmetric matrix,
• if self has eigenvalues smaller than 0.

impl MatQ

pub fn equal(self, other: MatZ) -> bool

impl MatQ

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 MatQ instance of the provided dimensions.

Examples

use qfall_math::rational::MatQ;

let matrix = MatQ::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::rational::MatQ;

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

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

Panics …

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

impl MatQ

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

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

Examples

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

let matrix = MatQ::from_str("[[1/2, 2],[3/7, 4]]").unwrap();
let matrix_invert = matrix.det().unwrap();

Errors and Failures

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

impl MatQ

pub fn collect_entries_f64(&self) -> Vec<Vec<f64>>

Returns a copy of all entries of self as f64 values in Vectors s.t. the resulting vector can be used as entries_f64[i][j] to access the entry in row i and column j.

WARNING: The return is system dependent if any entry of the matrix is is too large or too small to fit in an f64, i.e. the value should be within f64::MIN and f64::MAX. It the entry can’t be represented exactly, it will be rounded towards zero.

Examples

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

let mat = MatQ::from_str("[[1/1, 2],[3/1, 4],[5/1, 6]]").unwrap();

let entries_f64 = mat.collect_entries_f64();

assert_eq!(entries_f64[0][1], 2.0);

impl MatQ

pub fn gso(&self) -> Self

Computes the Gram-Schmidt Orthogonalization of the matrix and returns a MatQ with the corresponding matrix.

Examples

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

let mat = MatQ::from_str("[[1/2, 1],[2, 5]]").unwrap();
let mat_gso = mat.gso();

impl MatQ

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::rational::MatQ;
use qfall_math::traits::*;
use std::str::FromStr;

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

impl MatQ

pub fn norm_l_2_infty_sqrd(&self) -> Q

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::rational::{MatQ, Q};
use std::str::FromStr;

let mat = MatQ::from_str("[[2, 3],[-2/1, 0]]").unwrap();

let eucl_norm = mat.norm_l_2_infty_sqrd();

// 3^2 + 0^2 = 9
assert_eq!(Q::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::rational::{Q, MatQ};
use std::str::FromStr;

let mat = MatQ::from_str("[[4/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) -> Q

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::rational::{MatQ, Q};
use std::str::FromStr;

let mat = MatQ::from_str("[[2, 6/2],[2, 0]]").unwrap();

let eucl_norm = mat.norm_l_infty_infty();

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

impl MatQ

pub fn is_identity(&self) -> bool

Checks if a MatQ is the identity matrix.

Returns true if every diagonal entry of the upper square matrix is 1 and all other entries are 0.

Examples

use qfall_math::rational::MatQ;

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

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

let value = MatQ::from_str("[[1, 0],[0, 1],[0, 0]]").unwrap();
assert!(value.is_identity());

pub fn is_square(&self) -> bool

Checks if a MatQ is a square matrix.

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

Examples

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

let value = MatQ::from_str("[[4/7, 0],[5/8, 1/9]]").unwrap();
assert!(value.is_square());

pub fn is_zero(&self) -> bool

Checks if every entry of a MatQ is 0.

Returns true if every entry is 0.

Examples

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

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

pub fn is_symmetric(&self) -> bool

Checks if a MatQ is symmetric.

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

Examples

use qfall_math::rational::MatQ;

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

impl MatQ

pub fn floor(&self) -> MatZ

Rounds all entries of the given rational matrix MatQ down to the next integer as a MatZ.

Examples

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

let value = MatQ::from_str("[[5/2, 1]]").unwrap();
assert_eq!(MatZ::from_str("[[2, 1]]").unwrap(), value.floor());

let value = MatQ::from_str("[[-5/2, 1]]").unwrap();
assert_eq!(MatZ::from_str("[[-3, 1]]").unwrap(), value.floor());

pub fn ceil(&self) -> MatZ

Rounds all entries of the given rational matrix MatQ up to the next integer as a MatZ.

Examples

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

let value = MatQ::from_str("[[5/2, 1]]").unwrap();
assert_eq!(MatZ::from_str("[[3, 1]]").unwrap(), value.ceil());

let value = MatQ::from_str("[[-5/2, 1]]").unwrap();
assert_eq!(MatZ::from_str("[[-2, 1]]").unwrap(), value.ceil());

pub fn round(&self) -> MatZ

Rounds all entries of the given rational matrix MatQ to the closest integer as a MatZ.

Examples

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

let value = MatQ::from_str("[[5/2, 1]]").unwrap();
assert_eq!(MatZ::from_str("[[3, 1]]").unwrap(), value.round());

let value = MatQ::from_str("[[-5/2, 1]]").unwrap();
assert_eq!(MatZ::from_str("[[-2, 1]]").unwrap(), value.round());

pub fn simplify(&self, precision: impl Into<Q>) -> MatQ

Returns a matrix, where each entry was simplified using Q::simplify, i.e. each entry becomes the smallest rational with the smallest denominator in the range \[entry - |precision|, entry + |precision|\].

This function allows to free memory in exchange for the specified loss of precision (see Example 3). Be aware that this loss of precision is propagated by arithmetic operations depending on the size of the matrices. This functions allows to trade precision for efficiency.

This function ensures that simplifying does not change the sign of any entry in the matrix.

Parameters:

• precision: the precision the new entries can differ from self. Note that the absolute value is relevant, not the sign.

Returns a new MatQ with each entry being the simplest fraction within the defined range.

Examples

use qfall_math::rational::{MatQ, Q};
use qfall_math::traits::{MatrixGetEntry, MatrixSetEntry};
let mut matrix = MatQ::new(1, 2);
matrix.set_entry(0, 0, Q::from((17, 20))).unwrap();
let precision = Q::from((1, 20));

let matrix_simplified = matrix.simplify(precision);

assert_eq!(Q::from((4, 5)), matrix_simplified.get_entry(0, 0).unwrap());

use qfall_math::rational::{MatQ, Q};
use qfall_math::traits::{MatrixGetEntry, MatrixSetEntry};
let mut matrix = MatQ::new(2, 1);
matrix.set_entry(0, 0, Q::from((3, 2))).unwrap();

let mat_simplified = matrix.simplify(0.5);

assert_eq!(Q::ONE, mat_simplified.get_entry(0, 0).unwrap());

Simplify with reasonable precision loss

This example uses Q::INV_MAX32, i.e. a loss of precision of at most 1 / 2^31 - 2 behind the decimal point. If you require higher precision, Q::INV_MAX62 is available.

use qfall_math::rational::{MatQ, Q};
use qfall_math::traits::{MatrixGetEntry, MatrixSetEntry};
let mut matrix = MatQ::new(1, 1);
matrix.set_entry(0, 0, Q::PI).unwrap();

let mat_simplified = matrix.simplify(Q::INV_MAX32);

let entry_simplified = mat_simplified.get_entry(0, 0).unwrap();

assert_ne!(&Q::PI, &entry_simplified);
assert!(&entry_simplified >= &(Q::PI - Q::INV_MAX32));
assert!(&entry_simplified <= &(Q::PI + Q::INV_MAX32));

pub fn randomized_rounding(&self, r: impl Into<Q>) -> Result<MatZ, MathError>

Performs the randomized rounding algorithm entrywise by sampling from a discrete Gaussian over the integers shifted by self with gaussian parameter r.

Parameters:

• r: specifies the Gaussian parameter, which is proportional to the standard deviation sigma * sqrt(2 * pi) = r

Returns the rounded matrix as a MatZ or an error if r < 0.

Examples

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

let value = MatQ::from_str("[[5/2, 1]]").unwrap();
let rounded = value.randomized_rounding(3).unwrap();

Errors and Failures

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

This function implements randomized rounding according to:

• [1] Peikert, C. (2010, August). An efficient and parallel Gaussian sampler for lattices. In: Annual Cryptology Conference (pp. 80-97). https://link.springer.com/chapter/10.1007/978-3-642-14623-7_5

impl MatQ

pub fn sample_gauss( center: &MatQ, sigma: impl Into<f64>, ) -> Result<MatQ, MathError>

Chooses a MatQ instance according to the continuous Gaussian distribution. Here, each entry is chosen according to the provided distribution.

Parameters:

• center: specifies the center for each entry of the matrix individually
• sigma: specifies the standard deviation

Returns new MatQ sample chosen according to the specified continuous Gaussian distribution or a MathError if the specified parameters were not chosen appropriately (sigma > 0).

Examples

use qfall_math::rational::MatQ;

let sample = MatQ::sample_gauss(&MatQ::new(5, 5), 1).unwrap();

Errors and Failures

• Returns a MathError of type NonPositive if sigma <= 0.

pub fn sample_gauss_same_center( num_rows: impl TryInto<i64> + Display, num_cols: impl TryInto<i64> + Display, center: impl Into<Q>, sigma: impl Into<f64>, ) -> Result<MatQ, MathError>

Chooses a MatQ instance according to the continuous Gaussian distribution. Here, each entry is chosen according to the provided distribution and each entry is sampled with the same center.

Parameters:

• num_rows: specifies the number of rows of the sampled matrix
• num_cols: specifies the number of columns of the sampled matrix
• center: specifies the same center for each entry of the matrix
• sigma: specifies the standard deviation

Returns new MatQ sample chosen according to the specified continuous Gaussian distribution or a MathError if the specified parameters were not chosen appropriately (sigma > 0).

Examples

use qfall_math::rational::{Q, MatQ};

let center = Q::from((5,2));

let sample = MatQ::sample_gauss_same_center(5, 5, &center, 1).unwrap();

Errors and Failures

• Returns a MathError of type NonPositive if sigma <= 0.

Panics …

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

impl MatQ

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::rational::MatQ;

let mut matrix = MatQ::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::rational::MatQ;

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

impl MatQ

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::rational::MatQ;
use std::str::FromStr;
let mat = MatQ::from_str("[[3, 2, 1]]").unwrap();
let cmp = MatQ::from_str("[[1, 2, 3]]").unwrap();

let sorted = mat.sort_by_column(MatQ::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::{rational::{MatQ, Q}, error::MathError, traits::{MatrixDimensions, MatrixGetEntry}};
use std::str::FromStr;
let mat = MatQ::from_str("[[3, 2, 1]]").unwrap();
let cmp = MatQ::from_str("[[1, 2, 3]]").unwrap();

fn custom_cond_func(matrix: &MatQ) -> Result<Q, MathError> {
    let mut sum = Q::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::rational::MatQ;
use std::str::FromStr;
let mat = MatQ::from_str("[[3],[2],[1]]").unwrap();
let cmp = MatQ::from_str("[[1],[2],[3]]").unwrap();

let sorted = mat.sort_by_row(MatQ::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::{rational::{MatQ, Q}, error::MathError, traits::{MatrixDimensions, MatrixGetEntry}};
use std::str::FromStr;
let mat = MatQ::from_str("[[3],[2],[1]]").unwrap();
let cmp = MatQ::from_str("[[1],[2],[3]]").unwrap();

fn custom_cond_func(matrix: &MatQ) -> Result<Q, MathError> {
    let mut sum = Q::ZERO;
    for entry in matrix.get_entries_rowwise(){
        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 MatQ

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 MatQ

pub fn to_string_decimal(&self, nr_decimal_digits: usize) -> String

Outputs a representation of MatQ with the decimal representation of each entry with the specified number of decimal digits. If an entry can’t be represented exactly, it provides the closest value representable with nr_decimal_digits rounded towards zero.

WARNING: This function converts every entry into an f64 before outputting the decimal representation. Thus, values that can’t be represented exactly by a f64 will lose some precision. For large values, e.g. of size 2^64 the deviation to the original value might be within the size of 1_000.

Parameters:

• nr_decimal_digits: specifies the number of decimal digits that will be a part of the output String

Returns the matrix in form of a String. For matrix [[1/2],[5/3]] the String looks like this [[0.50],[1.66]] if nr_decimal_digits = 2.

Examples

use qfall_math::rational::MatQ;
use std::str::FromStr;
let matrix = MatQ::from_str("[[5/2, 2],[-2/3, 4/3]]").unwrap();

let decimal_repr = matrix.to_string_decimal(3);

impl MatQ

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

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

Examples

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

let matrix = MatQ::from_str("[[1/2, 2],[3/7, 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 MatQ

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::rational::MatQ;
use std::str::FromStr;

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

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

impl MatQ

pub unsafe fn get_fmpq_mat_struct(&mut self) -> &mut fmpq_mat_struct

Returns a mutable reference to the field matrix of type fmpq_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 MatQ

pub unsafe fn set_fmpq_mat_struct(&mut self, flint_struct: fmpq_mat_struct)

Sets the field matrix of type fmpq_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 MatQ

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

Returns the dot product of two vectors of type MatQ. Note that the dimensions of the two vectors are irrelevant for the dot product.

Parameters:

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

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

Examples

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

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

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

assert_eq!(Q::from(13), dot_prod);

Errors and Failures

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

impl MatQ

pub fn is_row_vector(&self) -> bool

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

Examples

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

let row_vec = MatQ::from_str("[[1, 2, 3/2]]").unwrap();
let col_vec = MatQ::from_str("[[1/4],[2],[3]]").unwrap();

assert!(row_vec.is_row_vector());
assert!(!col_vec.is_row_vector());

pub fn is_column_vector(&self) -> bool

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

Examples

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

let row_vec = MatQ::from_str("[[1/1, 2, 3]]").unwrap();
let col_vec = MatQ::from_str("[[1],[2/3],[3]]").unwrap();

assert!(col_vec.is_column_vector());
assert!(!row_vec.is_column_vector());

pub fn is_vector(&self) -> bool

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

Examples

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

let row_vec = MatQ::from_str("[[1, 2/2, 3/1]]").unwrap();
let col_vec = MatQ::from_str("[[1],[2],[3/2]]").unwrap();

assert!(row_vec.is_vector());
assert!(col_vec.is_vector());

pub fn has_single_entry(&self) -> bool

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

Examples

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

let vec = MatQ::from_str("[[1/2]]").unwrap();

assert!(vec.has_single_entry());

impl MatQ

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

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

Examples

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

let vec = MatQ::from_str("[[1],[2/1],[6/2]]").unwrap();

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

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

Errors and Failures

• Returns a MathError of type MathError::VectorFunctionCalledOnNonVector if the given MatQ 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 MatQ instance is not a (row or column) vector.

Examples

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

let vec = MatQ::from_str("[[2],[2/1],[4/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 MatQ instance is not a (row or column) vector.

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

Returns the infinity norm or ∞-norm of the given (row or column) vector.

Examples

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

let vec = MatQ::from_str("[[1/1],[2],[6/2]]").unwrap();

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

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

Errors and Failures

• Returns a MathError of type MathError::VectorFunctionCalledOnNonVector if the given MatQ 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 for &MatQ

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

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

Parameters:

• other: specifies the value to add to self

Returns the sum of both numbers as a MatQ.

Examples

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

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

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

Panics …

• if the dimensions of both matrices mismatch.

type Output = MatQ

The resulting type after applying the + operator.

impl AddAssign<&MatQ> for MatQ

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

Computes the addition of self and other reusing the memory of self. AddAssign can be used on MatQ in combination with MatQ and MatZ.

Parameters:

• other: specifies the value to add to self

Examples

use qfall_math::{rational::MatQ, integer::MatZ};
let mut a = MatQ::identity(2, 2);
let b = MatQ::new(2, 2);
let c = MatZ::new(2, 2);

a += &b;
a += b;
a += &c;
a += c;

Panics …

• if the matrix dimensions mismatch.

impl AddAssign<&MatZ> for MatQ

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

Documentation at MatQ::add_assign.

impl AddAssign<MatZ> for MatQ

fn add_assign(&mut self, other: MatZ)

Documentation at MatQ::add_assign.

impl AddAssign for MatQ

fn add_assign(&mut self, other: MatQ)

Documentation at MatQ::add_assign.

impl Clone for MatQ

fn clone(&self) -> Self

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

Examples

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

let string = String::from("[[1/2, 2/3, 3/4],[3/1, 4/2, 5/4]]");
let a = MatQ::from_str(&string).unwrap();
let b = a.clone();

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

Performs copy-assignment from source.

impl CompareBase<&MatQ> 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 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 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<Rational: Into<Q>> CompareBase<Rational> 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 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 Concatenate for &MatQ

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::rational::MatQ;

let mat_1 = MatQ::new(13, 5);
let mat_2 = MatQ::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::rational::MatQ;

let mat_1 = MatQ::new(17, 5);
let mat_2 = MatQ::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 = MatQ

impl Debug for MatQ

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for MatQ

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

where D: Deserializer<'de>,

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

impl Display for MatQ

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

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

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

Examples

use qfall_math::rational::MatQ;
use core::fmt;
use std::str::FromStr;

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

use qfall_math::rational::MatQ;
use core::fmt;
use std::str::FromStr;

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

impl Div<&Q> for &MatQ

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

Implements the Div trait for a MatQ by a Q rational. Div is implemented for any combination of owned and borrowed values.

Parameters:

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

Returns the division of self by scalar as a MatQ.

Examples

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

let matq_1 = MatQ::from_str("[[1, 2, 3],[4, 5/4, -1]]").unwrap();
let rational = Q::from((2,3));

let matq_2 = &matq_1 / &rational;

Panics …

• if the scalar is 0.

type Output = MatQ

The resulting type after applying the / operator.

impl Div<&Z> for &MatQ

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

Implements the Div trait for a MatQ by a Z integer. Div is implemented for any combination of owned and borrowed values.

Parameters:

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

Returns the division of self by scalar as a MatQ.

Examples

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

let matq_1 = MatQ::from_str("[[1, 2, 3],[4, 5/4, -1]]").unwrap();
let rational = Q::from((2,3));

let matq_2 = &matq_1 / &rational;

type Output = MatQ

The resulting type after applying the / operator.

impl DivAssign<&Q> for MatQ

fn div_assign(&mut self, scalar: &Q)

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

Parameters:

• other: specifies the value to multiply to self

Divides self coordinate-wise by other returning a MatQ.

Examples

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

let mut matq = MatQ::from_str(&format!("[[1, 2, 3],[4, 5/4, -1]]")).unwrap();
let q = Q::from((3, 4));
let z = Z::from(5);

matq /= &q;
matq /= q;
matq /= &z;
matq /= z;
matq /= -1;
matq /= 2;

Panics …

• if the scalar is 0.

impl DivAssign<&Z> for MatQ

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

Documentation at MatQ::div_assign.

impl DivAssign<Q> for MatQ

fn div_assign(&mut self, other: Q)

Documentation at MatQ::div_assign.

impl DivAssign<Z> for MatQ

fn div_assign(&mut self, other: Z)

Documentation at MatQ::div_assign.

impl DivAssign<f32> for MatQ

fn div_assign(&mut self, other: f32)

Documentation at MatQ::div_assign.

impl DivAssign<f64> for MatQ

fn div_assign(&mut self, other: f64)

Documentation at MatQ::div_assign.

impl DivAssign<i16> for MatQ

fn div_assign(&mut self, other: i16)

Documentation at MatQ::div_assign.

impl DivAssign<i32> for MatQ

fn div_assign(&mut self, other: i32)

Documentation at MatQ::div_assign.

impl DivAssign<i64> for MatQ

fn div_assign(&mut self, other: i64)

Documentation at MatQ::div_assign.

impl DivAssign<i8> for MatQ

fn div_assign(&mut self, other: i8)

Documentation at MatQ::div_assign.

impl DivAssign<u16> for MatQ

fn div_assign(&mut self, other: u16)

Documentation at MatQ::div_assign.

impl DivAssign<u32> for MatQ

fn div_assign(&mut self, other: u32)

Documentation at MatQ::div_assign.

impl DivAssign<u64> for MatQ

fn div_assign(&mut self, other: u64)

Documentation at MatQ::div_assign.

impl DivAssign<u8> for MatQ

fn div_assign(&mut self, other: u8)

Documentation at MatQ::div_assign.

impl Drop for MatQ

fn drop(&mut self)

Drops the given MatQ value and frees the allocated memory.

Examples

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

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

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

let string = String::from("[[1/2, 2/3, 3/4],[3/1, 4/2, 5/4]]");
let a = MatQ::from_str(&string).unwrap();
drop(a); // explicitly drops a's value

impl From<&MatQ> for MatQ

fn from(value: &MatQ) -> Self

Alias for MatQ::clone.

impl From<&MatQ> for String

fn from(value: &MatQ) -> Self

Converts a MatQ 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::rational::MatQ;
use std::str::FromStr;
let matrix = MatQ::from_str("[[6/7, 1],[5, 2/3]]").unwrap();

let string: String = matrix.into();

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<MatQ> for String

fn from(value: MatQ) -> Self

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

impl From<MatZ> for MatQ

fn from(value: MatZ) -> Self

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

impl FromCoefficientEmbedding<&MatQ> for PolyOverQ

fn from_coefficient_embedding(embedding: &MatQ) -> 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 PolyOverQ::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::{
    rational::{MatQ, PolyOverQ},
    traits::FromCoefficientEmbedding,
};

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

Panics …

• if the provided embedding is not a column vector.

impl FromStr for MatQ

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

Creates a MatQ matrix with entries in Q from a String.

Parameters:

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

Returns a MatQ 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 an entry is not formatted correctly.

Examples

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

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

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

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

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

let string = String::from("[[1/2, 2/3, 3/4],[4/5, 5/6, 6/7]]");
let matrix = MatQ::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 Q::from_str.

Panics …

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

type Err = MathError

The associated error which can be returned from parsing.

impl IntoCoefficientEmbedding<MatQ> for &PolyOverQ

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

Computes the coefficient embedding of the polynomial in a MatQ as a column vector, where the i-th entry of the vector corresponds to the i-th coefficient. It inverts the operation of PolyOverQ::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::{
    rational::{MatQ, PolyOverQ},
    traits::IntoCoefficientEmbedding,
};

let poly = PolyOverQ::from_str("3  17/3 3/2 -5").unwrap();
let vector = poly.into_coefficient_embedding(4);
let cmp_vector = MatQ::from_str("[[17/3],[3/2],[-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 MatQ

fn get_num_rows(&self) -> i64

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

Examples

use qfall_math::rational::MatQ;
use qfall_math::traits::*;

let matrix = MatQ::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::rational::MatQ;
use qfall_math::traits::*;

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

impl MatrixGetEntry<Q> for MatQ

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

Outputs the Q 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 Q 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::rational::{MatQ, Q};
use qfall_math::traits::MatrixGetEntry;
use std::str::FromStr;

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

assert_eq!(unsafe { matrix.get_entry_unchecked(0, 2) }, Q::from((3, 4)));
assert_eq!(unsafe { matrix.get_entry_unchecked(2, 1) }, Q::from(8));
assert_eq!(unsafe { matrix.get_entry_unchecked(2, 1) }, Q::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 MatQ

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::{rational::MatQ, traits::MatrixGetSubmatrix};
use std::str::FromStr;

let mat = MatQ::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 = MatQ::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<Rational: Into<Q>> MatrixSetEntry<Rational> for MatQ

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

Sets the value of a specific matrix entry according to a given value that implements Into<Q> 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::rational::MatQ;
use qfall_math::rational::Q;
use qfall_math::traits::*;

let mut matrix = MatQ::new(3, 3);
let value = Q::from((5, 2));

unsafe {
    matrix.set_entry_unchecked(0, 1, &value);
    matrix.set_entry_unchecked(2, 2, 5);
    matrix.set_entry_unchecked(0, 2, (2, 3));
}

assert_eq!("[[0, 5/2, 2/3],[0, 0, 0],[0, 0, 5]]", 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 MatQ

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::{rational::MatQ, traits::MatrixSetSubmatrix};
use std::str::FromStr;

let mut mat = MatQ::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 = MatQ::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 = MatQ::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 MatQ

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::{rational::MatQ, traits::MatrixSwaps};

let mut matrix = MatQ::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::{rational::MatQ, traits::MatrixSwaps};

let mut matrix = MatQ::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::{rational::MatQ, traits::MatrixSwaps};

let mut matrix = MatQ::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<&Q> for &MatQ

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

Implements the Mul trait for a MatQ 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::rational::MatQ;
use qfall_math::rational::Q;
use std::str::FromStr;

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

let mat_2 = &mat_1 * &rational;

type Output = MatQ

The resulting type after applying the * operator.

impl Mul<&Z> for &MatQ

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

Implements the Mul trait for a MatQ 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 MatQ.

Examples

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

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

let mat_2 = &mat_1 * &integer;

type Output = MatQ

The resulting type after applying the * operator.

impl Mul for &MatQ

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

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

Parameters:

• other: specifies the value to multiply with self

Returns the product of self and other as a MatQ.

Examples

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

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

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 = MatQ

The resulting type after applying the * operator.

impl MulAssign<&Q> for MatQ

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

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

Parameters:

• other: specifies the value to multiply to self

Returns the scalar of the matrix as a MatQ.

Examples

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

let mut a = MatQ::from_str("[[2, 1],[-1, 2/7]]").unwrap();
let b = Z::from(2);
let c = Q::from((2,5));

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

impl MulAssign<&Z> for MatQ

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

Documentation at MatQ::mul_assign.

impl MulAssign<Q> for MatQ

fn mul_assign(&mut self, other: Q)

Documentation at MatQ::mul_assign.

impl MulAssign<Z> for MatQ

fn mul_assign(&mut self, other: Z)

Documentation at MatQ::mul_assign.

impl MulAssign<f32> for MatQ

fn mul_assign(&mut self, other: f32)

Documentation at MatQ::mul_assign.

impl MulAssign<f64> for MatQ

fn mul_assign(&mut self, other: f64)

Documentation at MatQ::mul_assign.

impl MulAssign<i16> for MatQ

fn mul_assign(&mut self, other: i16)

Documentation at MatQ::mul_assign.

impl MulAssign<i32> for MatQ

fn mul_assign(&mut self, other: i32)

Documentation at MatQ::mul_assign.

impl MulAssign<i64> for MatQ

fn mul_assign(&mut self, other: i64)

Documentation at MatQ::mul_assign.

impl MulAssign<i8> for MatQ

fn mul_assign(&mut self, other: i8)

Documentation at MatQ::mul_assign.

impl MulAssign<u16> for MatQ

fn mul_assign(&mut self, other: u16)

Documentation at MatQ::mul_assign.

impl MulAssign<u32> for MatQ

fn mul_assign(&mut self, other: u32)

Documentation at MatQ::mul_assign.

impl MulAssign<u64> for MatQ

fn mul_assign(&mut self, other: u64)

Documentation at MatQ::mul_assign.

impl MulAssign<u8> for MatQ

fn mul_assign(&mut self, other: u8)

Documentation at MatQ::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 MatQ

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

Checks if two MatQ 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::rational::MatQ;
use std::str::FromStr;

let a_1 = MatQ::from_str("[[1/2, 2],[3/2, 4]]").unwrap();
let a_2 = MatQ::from_str("[[2/4, 2],[3/2, 4]]").unwrap();
assert!(a_1 == a_2);

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

// These are all equivalent and return false.
let compared: bool = (a_1 == b);
let compared: bool = (&a_1 == &b);
let compared: bool = (a_1.eq(&b));
let compared: bool = (MatQ::eq(&a_1, &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 Serialize for MatQ

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 MatQ.

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 for &MatQ

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

Implements the Sub trait for two matrices. Sub is implemented for any combination of MatQ and borrowed MatQ.

Parameters:

• other: specifies the value to subtract from self

Returns the result of the subtraction as a MatQ.

Examples

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

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

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

Panics …

• if the dimensions of both matrices mismatch.

type Output = MatQ

The resulting type after applying the - operator.

impl SubAssign<&MatQ> for MatQ

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

Computes the subtraction of self and other reusing the memory of self. SubAssign can be used on MatQ in combination with MatQ and MatZ.

Parameters:

• other: specifies the value to subrract from self

Examples

use qfall_math::{rational::MatQ, integer::MatZ};
let mut a = MatQ::identity(2, 2);
let b = MatQ::new(2, 2);
let c = MatZ::new(2, 2);

a -= &b;
a -= b;
a -= &c;
a -= c;

Panics …

• if the matrix dimensions mismatch.

impl SubAssign<&MatZ> for MatQ

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

Documentation at MatQ::sub_assign.

impl SubAssign<MatZ> for MatQ

fn sub_assign(&mut self, other: MatZ)

Documentation at MatQ::sub_assign.

impl SubAssign for MatQ

fn sub_assign(&mut self, other: MatQ)

Documentation at MatQ::sub_assign.

impl Tensor for MatQ

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::rational::MatQ;
use qfall_math::traits::Tensor;
use std::str::FromStr;

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

let mat_12 = mat_1.tensor_product(&mat_2);
let mat_21 = mat_2.tensor_product(&mat_1);

let res_12 = "[[1, 2, 1, 2],[3, 4, 3, 4],[2/3, 4/3, 2/3, 4/3],[2, 8/3, 2, 8/3]]";
let res_21 = "[[1, 1, 2, 2],[2/3, 2/3, 4/3, 4/3],[3, 3, 4, 4],[2, 2, 8/3, 8/3]]";
assert_eq!(mat_12, MatQ::from_str(res_12).unwrap());
assert_eq!(mat_21, MatQ::from_str(res_21).unwrap());

impl Eq for MatQ