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

    All Methods Instance Methods Abstract Methods Default Methods
    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`

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

2022 Copyright © Apache Software Foundation
| Follow @ApacheIgnite
Ignite Database and Caching Platform | : ver. 2.12.0
Release Date | : January 10 2022