org.apache.ignite.ml.math.primitives.matrix

Interface Matrix

All Superinterfaces:

Destroyable, Externalizable, MetaAttributes, Serializable, StorageOpsMetrics

All Known Implementing Classes:

AbstractMatrix, DenseMatrix, SparseMatrix, ViewMatrix

public interface Matrix
extends MetaAttributes, Externalizable, StorageOpsMetrics, Destroyable

A matrix interface.

Based on its flavor it can have vastly different implementations tailored for for different types of data (e.g. dense vs. sparse), different sizes of data or different operation optimizations.

Note also that not all operations can be supported by all underlying implementations. If an operation is not supported a UnsupportedOperationException is thrown. This exception can also be thrown in partial cases where an operation is unsupported only in special cases, e.g. where a given operation cannot be deterministically completed in polynomial time.

Based on ideas from Apache Mahout.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	Matrix.Element Holder for matrix's element.

Method Summary

Modifier and Type	Method and Description
Spliterator<Double>	allSpliterator() Gets spliterator for all values in this matrix.
Matrix	assign(double val) Assigns given value to all elements of this matrix.
Matrix	assign(double[][] vals) Assigns given values to this matrix.
Matrix	assign(IntIntToDoubleFunction fun) Assigns each matrix element to the value generated by given function.
Matrix	assign(Matrix mtx) Assigns values from given matrix to this matrix.
Matrix	assignColumn(int col, Vector vec) Assigns values from given vector to the specified column in this matrix.
Matrix	assignRow(int row, Vector vec) Assigns values from given vector to the specified row in this matrix.
int	columnSize() Gets number of columns in this matrix.
void	compute(int row, int col, IgniteTriFunction<Integer,Integer,Double,Double> f) Replace matrix entry with value oldVal at (row, col) with result of computing f(row, col, oldVal).
Matrix	copy() Clones this matrix.
boolean	density(double threshold) Calculates the density of the matrix based on supplied criteria.
default void	destroy() Destroys object if managed outside of JVM.
double	determinant() Returns matrix determinant using Laplace theorem.
Matrix	divide(double x) Divides each value in this matrix by the argument.
Vector	foldColumns(IgniteFunction<Vector,Double> fun) Collects the results of applying a given function to all columns in this matrix.
<T> T	foldMap(IgniteBiFunction<T,Double,T> foldFun, IgniteDoubleFunction<Double> mapFun, T zeroVal) Folds this matrix into a single value.
Vector	foldRows(IgniteFunction<Vector,Double> fun) Collects the results of applying a given function to all rows in this matrix.
double	get(int row, int col) Gets the matrix value at the provided location.
Vector	getCol(int col) Get a specific row from matrix.
Matrix.Element	getElement(int row, int col) Gets the matrix's element at the given coordinates.
Vector	getRow(int row) Get a specific row from matrix.
MatrixStorage	getStorage() Gets matrix storage model.
double	getX(int row, int col) Gets the matrix value at the provided location without checking boundaries.
IgniteUuid	guid() Auto-generated globally unique matrix ID.
Matrix	inverse() Returns the inverse matrix of this matrix
default boolean	isNumeric()
Matrix	like(int rows, int cols) Creates new empty matrix of the same underlying class but of different size.
Vector	likeVector(int crd) Creates new empty vector of compatible properties (similar or the same flavor) to this matrix.
Matrix	map(IgniteDoubleFunction<Double> fun) Maps all values in this matrix through a given function.
Matrix	map(Matrix mtx, IgniteBiFunction<Double,Double,Double> fun) Maps all values in this matrix through a given function.
Matrix.Element	maxElement() Gets the maximum element in this matrix.
double	maxValue() Gets the maximum value in this matrix.
Matrix.Element	minElement() Gets the minimum element in this matrix.
Matrix	minus(Matrix mtx) Creates new matrix where each value is a difference between corresponding value of this matrix and passed in argument matrix.
double	minValue() Gets the minimum value in this matrix.
int	nonZeroElements() Gets number of non-zero elements in this matrix.
Spliterator<Double>	nonZeroSpliterator() Gets spliterator for all non-zero values in this matrix.
Matrix	plus(double x) Creates new matrix where each value is a sum of the corresponding value of this matrix and argument value.
Matrix	plus(Matrix mtx) Creates new matrix where each value is a sum of corresponding values of this matrix and passed in argument matrix.
int	rowSize() Gets number of rows in this matrix.
Matrix	set(int row, int col, double val) Sets given value.
Matrix	setColumn(int col, double[] data) Sets values for given column.
Matrix	setRow(int row, double[] data) Sets values for given row.
Matrix	setX(int row, int col, double val) Sets given value without checking for index bounds.
double	sum() Gets sum of all elements in the matrix.
Matrix	swapColumns(int col1, int col2) Swaps two columns in this matrix.
Matrix	swapRows(int row1, int row2) Swaps two rows in this matrix.
Matrix	times(double x) Creates new matrix containing the product of given value and values in this matrix.
Matrix	times(Matrix mtx) Creates new matrix that is the product of multiplying this matrix and the argument matrix.
Vector	times(Vector vec) Creates new matrix that is the product of multiplying this matrix and the argument vector.
Matrix	transpose() Creates new matrix that is transpose of this matrix.
Vector	viewColumn(int col) Creates new view into matrix column .
Vector	viewDiagonal() Creates new view into matrix diagonal.
Vector	viewRow(int row) Creates new view into matrix row.

Methods inherited from interface org.apache.ignite.ml.math.MetaAttributes

getAttribute, getMetaStorage, hasAttribute, removeAttribute, setAttribute

Methods inherited from interface java.io.Externalizable

readExternal, writeExternal

Methods inherited from interface org.apache.ignite.ml.math.StorageOpsMetrics

isArrayBased, isDense, isDistributed

Method Detail

maxValue

double maxValue()

Gets the maximum value in this matrix.

Returns:

Maximum value in this matrix.

minValue

double minValue()

Gets the minimum value in this matrix.

Returns:

Minimum value in this matrix.

maxElement

Matrix.Element maxElement()

Gets the maximum element in this matrix.

Returns:

Maximum element in this matrix.

minElement

Matrix.Element minElement()

Gets the minimum element in this matrix.

Returns:

Minimum element in this matrix.

getElement

Matrix.Element getElement(int row,
                          int col)

Gets the matrix's element at the given coordinates.

Parameters:

row - Row index.

col - Column index.

Returns:

Element at the given coordinates.

swapRows

Matrix swapRows(int row1,
                int row2)

Swaps two rows in this matrix.

Parameters:

row1 - Row #1.

row2 - Row #2.

Returns:

This matrix.

swapColumns

Matrix swapColumns(int col1,
                   int col2)

Swaps two columns in this matrix.

Parameters:

col1 - Column #1.

col2 - Column #2.

Returns:

This matrix.

assign

Matrix assign(double val)

Assigns given value to all elements of this matrix.

Parameters:

val - Value to assign to all elements.

Returns:

This matrix.

assign

Matrix assign(double[][] vals)

Assigns given values to this matrix.

Parameters:

vals - Values to assign.

Returns:

This matrix.

Throws:

CardinalityException - Thrown if cardinalities mismatch.

assign

Matrix assign(Matrix mtx)

Assigns values from given matrix to this matrix.

Parameters:

mtx - Matrix to assign to this matrix.

Returns:

This matrix.

Throws:

CardinalityException - Thrown if cardinalities mismatch.

assign

Matrix assign(IntIntToDoubleFunction fun)

Assigns each matrix element to the value generated by given function.

Parameters:

fun - Function that takes the row and column and returns the value to assign.

Returns:

This matrix.

map

Matrix map(IgniteDoubleFunction<Double> fun)

Maps all values in this matrix through a given function.

Parameters:

fun - Mapping function.

Returns:

This matrix.

map

Matrix map(Matrix mtx,
           IgniteBiFunction<Double,Double,Double> fun)

Maps all values in this matrix through a given function.

For this matrix A, argument matrix B and the function F this method maps every cell x, y as: A(x,y) = fun(A(x,y), B(x,y)).

Parameters:

mtx - Argument matrix.

fun - Mapping function.

Returns:

This function.

Throws:

CardinalityException - Thrown if cardinalities mismatch.

nonZeroElements

int nonZeroElements()

Gets number of non-zero elements in this matrix.

Returns:

Number of non-zero elements in this matrix.

allSpliterator

Spliterator<Double> allSpliterator()

Gets spliterator for all values in this matrix.

Returns:

Spliterator for all values.

nonZeroSpliterator

Spliterator<Double> nonZeroSpliterator()

Gets spliterator for all non-zero values in this matrix.

Returns:

Spliterator for all non-zero values.

assignColumn

Matrix assignColumn(int col,
                    Vector vec)

Assigns values from given vector to the specified column in this matrix.

Parameters:

col - Column index.

vec - Vector to get values from.

Returns:

This matrix.

Throws:

CardinalityException - Thrown if cardinalities mismatch.

assignRow

Matrix assignRow(int row,
                 Vector vec)

Assigns values from given vector to the specified row in this matrix.

Parameters:

row - Row index.

vec - Vector to get values from.

Returns:

This matrix.

Throws:

CardinalityException - Thrown if cardinalities mismatch.

foldRows

Vector foldRows(IgniteFunction<Vector,Double> fun)

Collects the results of applying a given function to all rows in this matrix.

Parameters:

fun - Aggregating function.

Returns:

Vector of row aggregates.

foldColumns

Vector foldColumns(IgniteFunction<Vector,Double> fun)

Collects the results of applying a given function to all columns in this matrix.

Parameters:

fun - Aggregating function.

Returns:

Vector of column aggregates.

foldMap

<T> T foldMap(IgniteBiFunction<T,Double,T> foldFun,
              IgniteDoubleFunction<Double> mapFun,
              T zeroVal)

Folds this matrix into a single value.

Type Parameters:

T - Type of the folded value.

Parameters:

foldFun - Folding function that takes two parameters: accumulator and the current value.

mapFun - Mapping function that is called on each matrix cell before its passed to the accumulator (as its second parameter).

zeroVal - Zero value for fold function.

Returns:

Folded value of this matrix.

density

boolean density(double threshold)

Calculates the density of the matrix based on supplied criteria. Returns true if this matrix is denser than threshold with at least 80% confidence.

Parameters:

threshold - the threshold value [0, 1] of non-zero elements above which the matrix is considered dense.

columnSize

int columnSize()

Gets number of columns in this matrix.

Returns:

The number of columns in this matrix.

rowSize

int rowSize()

Gets number of rows in this matrix.

Returns:

The number of rows in this matrix.

divide

Matrix divide(double x)

Divides each value in this matrix by the argument.

Parameters:

x - Divider value.

Returns:

This matrix.

get

double get(int row,
           int col)

Gets the matrix value at the provided location.

Parameters:

row - Row index.

col - Column index.

Returns:

Matrix value.

Throws:

IndexException - Thrown in case of index is out of bound.

getX

double getX(int row,
            int col)

Gets the matrix value at the provided location without checking boundaries. This method is marginally quicker than its get(int, int) sibling.

Parameters:

row - Row index.

col - Column index.

Returns:

Matrix value.

getStorage

MatrixStorage getStorage()

Gets matrix storage model.

copy

Matrix copy()

Clones this matrix.

NOTE: new matrix will have the same flavor as the this matrix but a different ID.

Returns:

New matrix of the same underlying class, the same size and the same values.

like

Matrix like(int rows,
            int cols)

Creates new empty matrix of the same underlying class but of different size.

NOTE: new matrix will have the same flavor as the this matrix but a different ID.

Parameters:

rows - Number of rows for new matrix.

cols - Number of columns for new matrix.

Returns:

New matrix of the same underlying class and size.

likeVector

Vector likeVector(int crd)

Creates new empty vector of compatible properties (similar or the same flavor) to this matrix.

Parameters:

crd - Cardinality of the vector.

Returns:

Newly created empty vector "compatible" to this matrix.

minus

Matrix minus(Matrix mtx)

Creates new matrix where each value is a difference between corresponding value of this matrix and passed in argument matrix.

Parameters:

mtx - Argument matrix.

Returns:

New matrix of the same underlying class and size.

Throws:

CardinalityException - Thrown if cardinalities mismatch.

plus

Matrix plus(double x)

Creates new matrix where each value is a sum of the corresponding value of this matrix and argument value.

Parameters:

x - Value to add.

Returns:

New matrix of the same underlying class and size.

plus

Matrix plus(Matrix mtx)

Creates new matrix where each value is a sum of corresponding values of this matrix and passed in argument matrix.

Parameters:

mtx - Argument matrix.

Returns:

New matrix of the same underlying class and size.

Throws:

CardinalityException - Thrown if cardinalities mismatch.

guid

IgniteUuid guid()

Auto-generated globally unique matrix ID.

Returns:

Matrix GUID.

set

Matrix set(int row,
           int col,
           double val)

Sets given value.

Parameters:

row - Row index.

col - Column index.

val - Value to set.

Returns:

This matrix.

Throws:

IndexException - Thrown in case of either index is out of bound.

setRow

Matrix setRow(int row,
              double[] data)

Sets values for given row.

Parameters:

row - Row index.

data - Row data to set.

Returns:

This matrix.

Throws:

IndexException - Thrown in case of index is out of bound.

CardinalityException - Thrown if cardinalities mismatch.

getRow

Vector getRow(int row)

Get a specific row from matrix.

Parameters:

row - Row index.

Returns:

row.

setColumn

Matrix setColumn(int col,
                 double[] data)

Sets values for given column.

Parameters:

col - Column index.

data - Column data to set.

Returns:

This matrix.

Throws:

IndexException - Thrown in case of index is out of bound.

CardinalityException - Thrown if cardinalities mismatch.

getCol

Vector getCol(int col)

Get a specific row from matrix.

Parameters:

col - Col index.

Returns:

Col.

setX

Matrix setX(int row,
            int col,
            double val)

Sets given value without checking for index bounds. This method is marginally faster than its set(int, int, double) sibling.

Parameters:

row - Row index.

col - Column index.

val - Value to set.

Returns:

This matrix.

times

Matrix times(double x)

Creates new matrix containing the product of given value and values in this matrix.

Parameters:

x - Value to multiply.

Returns:

New matrix.

times

Matrix times(Matrix mtx)

Creates new matrix that is the product of multiplying this matrix and the argument matrix.

Parameters:

mtx - Argument matrix.

Returns:

New matrix.

Throws:

CardinalityException - Thrown if cardinalities mismatch.

times

Vector times(Vector vec)

Creates new matrix that is the product of multiplying this matrix and the argument vector.

Parameters:

vec - Argument vector.

Returns:

New matrix.

Throws:

CardinalityException - Thrown if cardinalities mismatch.

sum

double sum()

Gets sum of all elements in the matrix.

Returns:

Sum of all elements in this matrix.

transpose

Matrix transpose()

Creates new matrix that is transpose of this matrix.

Returns:

New transposed matrix.

viewRow

Vector viewRow(int row)

Creates new view into matrix row. Changes to the view will be propagated to this matrix.

Parameters:

row - Row index.

Returns:

New view.

Throws:

IndexException - Thrown in case of index is out of bound.

viewColumn

Vector viewColumn(int col)

Creates new view into matrix column . Changes to the view will be propagated to this matrix.

Parameters:

col - Column index.

Returns:

New view.

Throws:

IndexException - Thrown in case of index is out of bound.

viewDiagonal

Vector viewDiagonal()

Creates new view into matrix diagonal. Changes to the view will be propagated to this matrix.

Returns:

New view.

destroy

default void destroy()

Destroys object if managed outside of JVM. It's a no-op in all other cases.

Specified by:

destroy in interface Destroyable

compute

void compute(int row,
             int col,
             IgniteTriFunction<Integer,Integer,Double,Double> f)

Replace matrix entry with value oldVal at (row, col) with result of computing f(row, col, oldVal).

Parameters:

row - Row.

col - Column.

f - Function used for replacing.

determinant

double determinant()

Returns matrix determinant using Laplace theorem.

Returns:

A determinant for this matrix.

Throws:

CardinalityException - Thrown if matrix is not square.

inverse

Matrix inverse()

Returns the inverse matrix of this matrix

Returns:

Inverse of this matrix

isNumeric

default boolean isNumeric()

Specified by:

isNumeric in interface StorageOpsMetrics

Returns:

true if all stored data are values of Number class.