Trait rusty_machine::linalg::BaseMatrix

source · [−]
pub trait BaseMatrix<T> {

Show 38 methods    fn rows(&self) -> usize;
    fn cols(&self) -> usize;
    fn row_stride(&self) -> usize;
    fn as_ptr(&self) -> *const T;

    fn is_empty(&self) -> bool { ... }
    fn as_slice(&self) -> MatrixSlice<'_, T> { ... }
    unsafe fn get_unchecked(&self, index: [usize; 2]) -> &T { ... }
    fn get(&self, index: [usize; 2]) -> Option<&T> { ... }
    fn col(&self, index: usize) -> Column<'_, T> { ... }
    unsafe fn col_unchecked(&self, index: usize) -> Column<'_, T> { ... }
    fn row(&self, index: usize) -> Row<'_, T> { ... }
    unsafe fn row_unchecked(&self, index: usize) -> Row<'_, T> { ... }
    fn iter<'a>(&self) -> SliceIter<'a, T>
    where
        T: 'a,
    { ... }
    fn col_iter(&self) -> Cols<'_, T> { ... }
    fn row_iter(&self) -> Rows<'_, T> { ... }
    fn diag_iter(&self, k: DiagOffset) -> Diagonal<'_, T, Self> { ... }
    fn sum_rows(&self) -> Vector<T>
    where
        T: Copy + Zero<Output = T> + Add<T>,
    { ... }
    fn sum_cols(&self) -> Vector<T>
    where
        T: Copy + Zero<Output = T> + Add<T>,
    { ... }
    fn norm<N>(&self, norm: N) -> T
    where
        N: MatrixNorm<T, Self>,
        T: Float,
    { ... }
    fn metric<'a, 'b, B, M>(&'a self, mat: &'b B, metric: M) -> T
    where
        B: 'b + BaseMatrix<T>,
        M: MatrixMetric<'a, 'b, T, Self, B>,
    { ... }
    fn sum(&self) -> T
    where
        T: Copy + Zero<Output = T> + Add<T>,
    { ... }
    fn min(&self, axis: Axes) -> Vector<T>
    where
        T: Copy + PartialOrd<T>,
    { ... }
    fn max(&self, axis: Axes) -> Vector<T>
    where
        T: Copy + PartialOrd<T>,
    { ... }
    fn into_matrix(self) -> Matrix<T>
    where
        T: Copy,
    { ... }
    fn select_rows<'a, I>(&self, rows: I) -> Matrix<T>
    where
        T: Copy,
        I: IntoIterator<Item = &'a usize>,
        <I as IntoIterator>::IntoIter: ExactSizeIterator + Clone,
    { ... }
    fn select_cols<'a, I>(&self, cols: I) -> Matrix<T>
    where
        T: Copy,
        I: IntoIterator<Item = &'a usize>,
        <I as IntoIterator>::IntoIter: ExactSizeIterator + Clone,
    { ... }
    fn elemul(&self, m: &Self) -> Matrix<T>
    where
        T: Copy + Mul<T, Output = T>,
    { ... }
    fn elediv(&self, m: &Self) -> Matrix<T>
    where
        T: Copy + Div<T, Output = T>,
    { ... }
    fn select(&self, rows: &[usize], cols: &[usize]) -> Matrix<T>
    where
        T: Copy,
    { ... }
    fn hcat<S>(&self, m: &S) -> Matrix<T>
    where
        T: Copy,
        S: BaseMatrix<T>,
    { ... }
    fn vcat<S>(&self, m: &S) -> Matrix<T>
    where
        T: Copy,
        S: BaseMatrix<T>,
    { ... }
    fn diag(&self) -> Diagonal<'_, T, Self> { ... }
    fn transpose(&self) -> Matrix<T>
    where
        T: Copy,
    { ... }
    fn is_diag(&self) -> bool
    where
        T: Zero + PartialEq<T>,
    { ... }
    fn solve_u_triangular(&self, y: Vector<T>) -> Result<Vector<T>, Error>
    where
        T: Any + Float,
    { ... }
    fn solve_l_triangular(&self, y: Vector<T>) -> Result<Vector<T>, Error>
    where
        T: Any + Float,
    { ... }
    fn split_at(
        &self,
        mid: usize,
        axis: Axes
    ) -> (MatrixSlice<'_, T>, MatrixSlice<'_, T>) { ... }
    fn sub_slice<'a>(
        &self,
        start: [usize; 2],
        rows: usize,
        cols: usize
    ) -> MatrixSlice<'a, T>
    where
        T: 'a,
    { ... }

}
Expand description

Trait for immutable matrix structs.

Required Methods

Rows in the matrix.

Columns in the matrix.

Row stride in the matrix.

Top left index of the matrix.

Provided Methods

Returns true if the matrix contais no elements

Returns a MatrixSlice over the whole matrix.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let a = Matrix::new(3, 3, vec![2.0; 9]);
let b = a.as_slice();

Get a reference to an element in the matrix without bounds checking.

Get a reference to an element in the matrix.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};
 
let mat = matrix![0, 1;
                  3, 4;
                  6, 7];

assert_eq!(mat.get([0, 2]), None);
assert_eq!(mat.get([3, 0]), None);

assert_eq!( *mat.get([0, 0]).unwrap(), 0)

Returns the column of a matrix at the given index. None if the index is out of bounds.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let mat = matrix![0, 1, 2;
                  3, 4, 5;
                  6, 7, 8];
let col = mat.col(1);
let expected = matrix![1usize; 4; 7];
assert_matrix_eq!(*col, expected);
Panics

Will panic if the column index is out of bounds.

Returns the column of a matrix at the given index without doing a bounds check.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let mat = matrix![0, 1, 2;
                  3, 4, 5;
                  6, 7, 8];
let col = unsafe { mat.col_unchecked(2) };
let expected = matrix![2usize; 5; 8];
assert_matrix_eq!(*col, expected);

Returns the row of a matrix at the given index.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let mat = matrix![0, 1, 2;
                  3, 4, 5;
                  6, 7, 8];
let row = mat.row(1);
let expected = matrix![3usize, 4, 5];
assert_matrix_eq!(*row, expected);
Panics

Will panic if the row index is out of bounds.

Returns the row of a matrix at the given index without doing unbounds checking

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let mat = matrix![0, 1, 2;
                  3, 4, 5;
                  6, 7, 8];
let row = unsafe { mat.row_unchecked(2) };
let expected = matrix![6usize, 7, 8];
assert_matrix_eq!(*row, expected);

Returns an iterator over the matrix data.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let mat = matrix![0, 1, 2;
                  3, 4, 5;
                  6, 7, 8];
let slice = mat.sub_slice([1, 1], 2, 2);

let slice_data = slice.iter().map(|v| *v).collect::<Vec<usize>>();
assert_eq!(slice_data, vec![4, 5, 7, 8]);

Iterate over the columns of the matrix.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let a = matrix![0, 1;
                2, 3;
                4, 5];

let mut iter = a.col_iter();

assert_matrix_eq!(*iter.next().unwrap(), matrix![ 0; 2; 4 ]);
assert_matrix_eq!(*iter.next().unwrap(), matrix![ 1; 3; 5 ]);
assert!(iter.next().is_none());

Iterate over the rows of the matrix.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};
let a = matrix![0, 1, 2;
                3, 4, 5;
                6, 7, 8];

let mut iter = a.row_iter();

assert_matrix_eq!(*iter.next().unwrap(), matrix![ 0, 1, 2 ]);
assert_matrix_eq!(*iter.next().unwrap(), matrix![ 3, 4, 5 ]);
assert_matrix_eq!(*iter.next().unwrap(), matrix![ 6, 7, 8 ]);
assert!(iter.next().is_none());

Iterate over diagonal entries

Examples

use rulinalg::matrix::{DiagOffset, Matrix, BaseMatrix};

let a = matrix![0, 1, 2;
                3, 4, 5;
                6, 7, 8];
// Print super diag [1, 5]
for d in a.diag_iter(DiagOffset::Above(1)) {
    println!("{}", d);
}

// Print sub diag [3, 7]
// Equivalent to `diag_iter(DiagOffset::Below(1))`
for d in a.diag_iter(DiagOffset::from(-1)) {
    println!("{}", d);
}
Panics

If using an Above or Below offset which is out-of-bounds this function will panic.

This function will never panic if the Main diagonal offset is used.

The sum of the rows of the matrix.

Returns a Vector equal to the sums of elements over the matrices rows.

Note that the resulting vector is identical to the sums of elements along each column of the matrix.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let a = matrix![1.0, 2.0;
                3.0, 4.0];

let c = a.sum_rows();
assert_eq!(c, vector![4.0, 6.0]);

The sum of the columns of the matrix.

Returns a Vector equal to the sums of elements over the matrices columns.

Note that the resulting vector is identical to the sums of elements along each row of the matrix.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let a = matrix![1.0, 2.0;
                3.0, 4.0];

let c = a.sum_cols();
assert_eq!(c, vector![3.0, 7.0]);

Compute given matrix norm for matrix.

Examples
use rulinalg::matrix::BaseMatrix;
use rulinalg::norm::Euclidean;

let a = matrix![3.0, 4.0];
let c = a.norm(Euclidean);

assert_eq!(c, 5.0);

Compute the metric distance between two matrices.

Examples
use rulinalg::matrix::BaseMatrix;
use rulinalg::norm::Euclidean;

let a = matrix![3.0, 4.0;
                1.0, 2.0];
let b = matrix![2.0, 5.0;
                0.0, 3.0];

// Compute the square root of the sum of
// elementwise squared-differences
let c = a.metric(&b, Euclidean);

assert_eq!(c, 2.0);

The sum of all elements in the matrix

Examples
use rulinalg::matrix::BaseMatrix;

let a = matrix![1.0, 2.0;
                3.0, 4.0];

let c = a.sum();
assert_eq!(c, 10.0);

The min of the specified axis of the matrix.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix, Axes};

let a = matrix![1.0, 2.0;
                3.0, 4.0];

let cmin = a.min(Axes::Col);
assert_eq!(cmin, vector![1.0, 3.0]);

let rmin = a.min(Axes::Row);
assert_eq!(rmin, vector![1.0, 2.0]);

The max of the specified axis of the matrix.

Examples
use rulinalg::matrix::{BaseMatrix, Axes};

let a = matrix![1.0, 2.0;
                3.0, 4.0];

let cmax = a.max(Axes::Col);
assert_eq!(cmax, vector![2.0, 4.0]);

let rmax = a.max(Axes::Row);
assert_eq!(rmax, vector![3.0, 4.0]);

Convert the matrix struct into a owned Matrix.

Select rows from matrix

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let a = Matrix::<f64>::ones(3,3);

let b = &a.select_rows(&[2]);
assert_eq!(b.rows(), 1);
assert_eq!(b.cols(), 3);

let c = &a.select_rows(&[1,2]);
assert_eq!(c.rows(), 2);
assert_eq!(c.cols(), 3);
Panics
  • Panics if row indices exceed the matrix dimensions.

Select columns from matrix

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let a = Matrix::<f64>::ones(3,3);
let b = &a.select_cols(&[2]);
assert_eq!(b.rows(), 3);
assert_eq!(b.cols(), 1);

let c = &a.select_cols(&[1,2]);
assert_eq!(c.rows(), 3);
assert_eq!(c.cols(), 2);
Panics
  • Panics if column indices exceed the matrix dimensions.

The elementwise product of two matrices.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let a = matrix![1.0, 2.0;
                3.0, 4.0];
let b = matrix![1.0, 2.0;
                3.0, 4.0];

let c = &a.elemul(&b);
assert_matrix_eq!(c, &matrix![1.0, 4.0; 9.0, 16.0]);
}
Panics
  • The matrices have different row counts.
  • The matrices have different column counts.

The elementwise division of two matrices.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let a = matrix![1.0, 2.0;
                3.0, 4.0];
let b = matrix![1.0, 2.0;
                3.0, 4.0];

let c = &a.elediv(&b);
assert_matrix_eq!(c, &matrix![1.0, 1.0; 1.0, 1.0]);
Panics
  • The matrices have different row counts.
  • The matrices have different column counts.

Select block matrix from matrix

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let a = Matrix::<f64>::identity(3);
let b = &a.select(&[0,1], &[1,2]);

// We get the 2x2 block matrix in the upper right corner.
assert_eq!(b.rows(), 2);
assert_eq!(b.cols(), 2);

// Prints [0,0, 1,0]
println!("{:?}", b.data());
Panics
  • Panics if row or column indices exceed the matrix dimensions.

Horizontally concatenates two matrices. With self on the left.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let a = matrix![1.0, 2.0;
                3.0, 4.0;
                5.0, 6.0];
let b = matrix![4.0;
                5.0;
                6.0];

let c = &a.hcat(&b);
assert_eq!(c.cols(), a.cols() + b.cols());
assert_eq!(c[[1, 2]], 5.0);
Panics
  • Self and m have different row counts.

Vertically concatenates two matrices. With self on top.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let a = matrix![1.0, 2.0, 3.0;
                4.0, 5.0, 6.0];
let b = matrix![4.0, 5.0, 6.0];;

let c = &a.vcat(&b);
assert_eq!(c.rows(), a.rows() + b.rows());
assert_eq!(c[[2, 2]], 6.0);
Panics
  • Self and m have different column counts.

Extract the diagonal of the matrix

Examples


use rulinalg::matrix::BaseMatrix;

let a = matrix![1, 2, 3;
                4, 5, 6;
                7, 8, 9].diag().cloned().collect::<Vec<_>>();
let b = matrix![1, 2;
                3, 4;
                5, 6].diag().cloned().collect::<Vec<_>>();

assert_eq!(a, vec![1, 5, 9]);
assert_eq!(b, vec![1, 4]);

Tranposes the given matrix

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let mat = matrix![1.0, 2.0, 3.0;
                  4.0, 5.0, 6.0];

let expected = matrix![1.0, 4.0;
                       2.0, 5.0;
                       3.0, 6.0];
assert_matrix_eq!(mat.transpose(), expected);

Checks if matrix is diagonal.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix};

let a = matrix![1.0, 0.0;
                0.0, 1.0];
let a_diag = a.is_diag();

assert_eq!(a_diag, true);

let b = matrix![1.0, 0.0;
                1.0, 0.0];
let b_diag = b.is_diag();

assert_eq!(b_diag, false);

Solves an upper triangular linear system.

Given a matrix A and a vector b, this function returns the solution of the upper triangular system Ux = b, where U is the upper triangular part of A.

Examples
use rulinalg::matrix::BaseMatrix;
use std::f32;

let u = matrix![1.0, 2.0;
                0.0, 1.0];
let y = vector![3.0, 1.0];

let x = u.solve_u_triangular(y).expect("A solution should exist!");
assert!((x[0] - 1.0) < f32::EPSILON);
assert!((x[1] - 1.0) < f32::EPSILON);
Panics
  • Vector size and matrix column count are not equal.
Failures
  • There is no valid solution to the system (matrix is singular).
  • The matrix is empty.

Solves a lower triangular linear system.

Given a matrix A and a vector b, this function returns the solution of the lower triangular system Lx = b, where L is the lower triangular part of A.

Examples
use rulinalg::matrix::BaseMatrix;
use std::f32;

let l = matrix![1.0, 0.0;
                2.0, 1.0];
let y = vector![1.0, 3.0];

let x = l.solve_l_triangular(y).expect("A solution should exist!");
println!("{:?}", x);
assert!((x[0] - 1.0) < f32::EPSILON);
assert!((x[1] - 1.0) < f32::EPSILON);
Panics
  • Vector size and matrix column count are not equal.
Failures
  • There is no valid solution to the system (matrix is singular).
  • The matrix is empty.

Split the matrix at the specified axis returning two MatrixSlices.

Examples
use rulinalg::matrix::{Axes, Matrix, BaseMatrix};

let a = Matrix::new(3,3, vec![2.0; 9]);
let (b,c) = a.split_at(1, Axes::Row);

Produce a MatrixSlice from an existing matrix.

Examples
use rulinalg::matrix::{Matrix, BaseMatrix, MatrixSlice};

let a = Matrix::new(3,3, (0..9).collect::<Vec<usize>>());
let slice = MatrixSlice::from_matrix(&a, [1,1], 2, 2);
let new_slice = slice.sub_slice([0,0], 1, 1);

Implementors