Interface Matrix

All Superinterfaces:
Tensor
All Known Implementing Classes:
AtA, BandMatrix, DenseMatrix, SparseMatrix, SymmMatrix, Vector
public interface Matrix extends Tensor
Mathematical matrix interface. The most important methods are matrix-matrix multiplication, and matrix-vector multiplication. Matrix-matrix multiplication is the core operation in deep learning. Matrix-vector multiplication is the only operation needed in many iterative matrix algorithms, e.g. biconjugate gradient method for solving linear equations and power iteration and Lanczos algorithm for eigen decomposition, which are usually very efficient for very large and sparse matrices.

A matrix is a rectangular array of numbers. An item in a matrix is called an entry or an element. Entries are often denoted by a variable with two subscripts. Matrices of the same size can be added and subtracted entry-wise and matrices of compatible size can be multiplied. These operations have many of the properties of ordinary arithmetic, except that matrix multiplication is not commutative, that is, AB and BA are not equal in general.

Matrices are a key tool in linear algebra. One use of matrices is to represent linear transformations and matrix multiplication corresponds to composition of linear transformations. Matrices can also keep track of the coefficients in a system of linear equations. For a square matrix, the determinant and inverse matrix (when it exists) govern the behavior of solutions to the corresponding system of linear equations, and eigenvalues and eigenvectors provide insight into the geometry of the associated linear transformation.

There are several methods to render matrices into a more easily accessible form. They are generally referred to as matrix transformation or matrix decomposition techniques. The interest of all these decomposition techniques is that they preserve certain properties of the matrices in question, such as determinant, rank or inverse, so that these quantities can be calculated after applying the transformation, or that certain matrix operations are algorithmically easier to carry out for some types of matrices.

The LU decomposition factors matrices as a product of lower (L) and an upper triangular matrices (U). Once this decomposition is calculated, linear systems can be solved more efficiently, by a simple technique called forward and back substitution. Likewise, inverses of triangular matrices are algorithmically easier to calculate. The QR decomposition factors matrices as a product of an orthogonal (Q) and a right triangular matrix (R). QR decomposition is often used to solve the linear least squares problem, and is the basis for a particular eigenvalue algorithm, the QR algorithm. Singular value decomposition expresses any matrix A as a product UDV', where U and V are unitary matrices and D is a diagonal matrix. The eigen-decomposition or diagonalization expresses A as a product VDV-1, where D is a diagonal matrix and V is a suitable invertible matrix. If A can be written in this form, it is called diagonalizable.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    add(int i, int j, double x)
    Sets A[i,j] += x.
    default double
    apply(int i, int j)
    Returns A[i,j] for Scala users.
    Matrix
    copy()
    Returns a deep copy of matrix.
    default Vector
    diagonal()
    Returns the diagonal elements.
    default int
    dim()
    Returns the number of dimensions of tensor.
    void
    div(int i, int j, double x)
    Sets A[i,j] /= x.
    default Tensor
    get(int... index)
    Returns a portion of tensor given the index.
    double
    get(int i, int j)
    Returns A[i,j].
    default long
    length()
    Returns the number of tensor elements.
    static Matrix
    market(Path path)
    Reads a matrix from a Matrix Market File Format file.
    void
    mul(int i, int j, double x)
    Sets A[i,j] *= x.
    default Vector
    mv(double[] x)
    Matrix-vector multiplication A * x.
    default Vector
    mv(float[] x)
    Matrix-vector multiplication A * x.
    void
    mv(Transpose trans, double alpha, Vector x, double beta, Vector y)
    Matrix-vector multiplication.
    default Vector
    mv(Vector x)
    Matrix-vector multiplication A * x.
    default void
    mv(Vector work, int inputOffset, int outputOffset)
    Matrix-vector multiplication A * x.
    default void
    mv(Vector x, Vector y)
    Matrix-vector multiplication A * x.
    int
    ncol()
    Returns the number of columns.
    int
    nrow()
    Returns the number of rows.
    default Tensor
    reshape(int... shape)
    Returns a tensor with the same data and number of elements but with the specified shape.
    Matrix
    scale(double alpha)
    A *= alpha
    void
    set(int i, int j, double x)
    Sets A[i,j] = x.
    default Tensor
    set(Tensor value, int... index)
    Updates a sub-tensor in place.
    default int[]
    shape()
    Returns the shape of tensor.
    default int
    size(int dim)
    Returns the size of given dimension.
    void
    sub(int i, int j, double x)
    Sets A[i,j] -= x.
    default double[][]
    toArray(double[][] a)
    Returns a two-dimensional array containing all the elements in this matrix.
    default float[][]
    toArray(float[][] a)
    Returns a two-dimensional array containing all the elements in this matrix.
    default String
    toString(boolean full)
    Returns the string representation of matrix.
    default String
    toString(int m, int n)
    Returns the string representation of matrix.
    default double
    trace()
    Returns the matrix trace.
    Matrix
    transpose()
    Returns the transpose of matrix.
    default Vector
    tv(double[] x)
    Matrix-vector multiplication A * x.
    default Vector
    tv(float[] x)
    Matrix-vector multiplication A * x.
    default Vector
    tv(Vector x)
    Matrix-vector multiplication A' * x.
    default void
    tv(Vector work, int inputOffset, int outputOffset)
    Matrix-vector multiplication A' * x.
    default void
    tv(Vector x, Vector y)
    Matrix-vector multiplication A' * x.
    default void
    update(int i, int j, double x)
    Sets A[i,j] = x for Scala users.
    default Vector
    vector(double[] x)
    Creates a column vector of same scalar type.
    default Vector
    vector(float[] x)
    Creates a column vector of same scalar type.
    default Vector
    vector(int size)
    Creates a column vector of same scalar type.
    default double
    xAx(Vector x)
    Returns the quadratic form x' * A * x.

    Methods inherited from interface Tensor

    scalarType

  • Method Details

    • nrow

      int nrow()
      Returns the number of rows.
      Returns:
      the number of rows.

    • ncol

      int ncol()
      Returns the number of columns.
      Returns:
      the number of columns.

    • dim

      default int dim()
      Description copied from interface: Tensor
      Returns the number of dimensions of tensor.
      Specified by:
      dim in interface Tensor
      Returns:
      the number of dimensions of tensor

    • size

      default int size(int dim)
      Description copied from interface: Tensor
      Returns the size of given dimension.
      Specified by:
      size in interface Tensor
      Parameters:
      dim - dimension index.
      Returns:
      the size of given dimension.

    • length

      default long length()
      Description copied from interface: Tensor
      Returns the number of tensor elements. For tensors with packed storage (e.g., BandMatrix, SparseMatrix, SymmMatrix), it returns the number of non-zero elements.
      Specified by:
      length in interface Tensor
      Returns:
      the number of tensor elements.

    • shape

      default int[] shape()
      Description copied from interface: Tensor
      Returns the shape of tensor. That is a list of the extent of each dimension.
      Specified by:
      shape in interface Tensor
      Returns:
      the shape of tensor.

    • reshape

      default Tensor reshape(int... shape)
      Description copied from interface: Tensor
      Returns a tensor with the same data and number of elements but with the specified shape. This method returns a view if shape is compatible with the current shape.
      Specified by:
      reshape in interface Tensor
      Parameters:
      shape - the new shape of tensor.
      Returns:
      the tensor with the specified shape.

    • set

      default Tensor set(Tensor value, int... index)
      Description copied from interface: Tensor
      Updates a sub-tensor in place.
      Specified by:
      set in interface Tensor
      Parameters:
      value - the sub-tensor.
      index - the index.
      Returns:
      this tensor.

    • get

      default Tensor get(int... index)
      Description copied from interface: Tensor
      Returns a portion of tensor given the index.
      Specified by:
      get in interface Tensor
      Parameters:
      index - the index along the dimensions.
      Returns:
      the sub-tensor.

    • toString

      default String toString(boolean full)
      Returns the string representation of matrix.
      Parameters:
      full - Print the full matrix if true. Otherwise, print only top left 7 x 7 submatrix.
      Returns:
      the string representation of matrix.

    • toString

      default String toString(int m, int n)
      Returns the string representation of matrix.
      Parameters:
      m - the number of rows to print.
      n - the number of columns to print.
      Returns:
      the string representation of matrix.

    • vector

      default Vector vector(int size)
      Creates a column vector of same scalar type.
      Parameters:
      size - the vector size.
      Returns:
      the vector.

    • vector

      default Vector vector(double[] x)
      Creates a column vector of same scalar type.
      Parameters:
      x - the initial vector values.
      Returns:
      the vector.

    • vector

      default Vector vector(float[] x)
      Creates a column vector of same scalar type.
      Parameters:
      x - the initial vector values.
      Returns:
      the vector.

    • get

      double get(int i, int j)
      Returns A[i,j].
      Parameters:
      i - the row index.
      j - the column index.
      Returns:
      the matrix element value.

    • apply

      default double apply(int i, int j)
      Returns A[i,j] for Scala users.
      Parameters:
      i - the row index.
      j - the column index.
      Returns:
      the matrix element value.

    • set

      void set(int i, int j, double x)
      Sets A[i,j] = x.
      Parameters:
      i - the row index.
      j - the column index.
      x - the matrix element value.

    • update

      default void update(int i, int j, double x)
      Sets A[i,j] = x for Scala users.
      Parameters:
      i - the row index.
      j - the column index.
      x - the matrix element value.

    • add

      void add(int i, int j, double x)
      Sets A[i,j] += x.
      Parameters:
      i - the row index.
      j - the column index.
      x - the operand.

    • sub

      void sub(int i, int j, double x)
      Sets A[i,j] -= x.
      Parameters:
      i - the row index.
      j - the column index.
      x - the operand.

    • mul

      void mul(int i, int j, double x)
      Sets A[i,j] *= x.
      Parameters:
      i - the row index.
      j - the column index.
      x - the operand.

    • div

      void div(int i, int j, double x)
      Sets A[i,j] /= x.
      Parameters:
      i - the row index.
      j - the column index.
      x - the operand.

    • scale

      Matrix scale(double alpha)
      A *= alpha
      Parameters:
      alpha - the scaling factor.
      Returns:
      this matrix.

    • diagonal

      default Vector diagonal()
      Returns the diagonal elements.
      Returns:
      the diagonal elements.

    • trace

      default double trace()
      Returns the matrix trace. The sum of the diagonal elements.
      Returns:
      the matrix trace.

    • toArray

      default double[][] toArray(double[][] a)
      Returns a two-dimensional array containing all the elements in this matrix.
      Parameters:
      a - the array into which the elements of the matrix are to be stored if it is big enough; otherwise, a new array is allocated.
      Returns:
      an array containing the elements of the vector.

    • toArray

      default float[][] toArray(float[][] a)
      Returns a two-dimensional array containing all the elements in this matrix.
      Parameters:
      a - the array into which the elements of the matrix are to be stored if it is big enough; otherwise, a new array is allocated.
      Returns:
      an array containing the elements of the vector.

    • copy

      Matrix copy()
      Returns a deep copy of matrix.
      Returns:
      a deep copy of matrix.

    • transpose

      Matrix transpose()
      Returns the transpose of matrix. The transpose may share the storage with this matrix.
      Returns:
      the transpose of matrix.

    • mv

      void mv(Transpose trans, double alpha, Vector x, double beta, Vector y)
      Matrix-vector multiplication. 
          y = alpha * A * x + beta * y
      Parameters:
      trans - normal, transpose, or conjugate transpose operation on the matrix.
      alpha - the scalar alpha.
      x - the input vector.
      beta - the scalar beta. When beta is supplied as zero, y need not be set on input.
      y - the input and output vector.

    • mv

      default Vector mv(Vector x)
      Matrix-vector multiplication A * x.
      Parameters:
      x - the vector.
      Returns:
      the matrix-vector multiplication A * x.

    • mv

      default void mv(Vector x, Vector y)
      Matrix-vector multiplication A * x.
      Parameters:
      x - the input vector.
      y - the input and output vector.

    • mv

      default void mv(Vector work, int inputOffset, int outputOffset)
      Matrix-vector multiplication A * x.
      Parameters:
      work - the workspace for both input and output vector.
      inputOffset - the offset of input vector in workspace.
      outputOffset - the offset of output vector in workspace.

    • tv

      default Vector tv(Vector x)
      Matrix-vector multiplication A' * x.
      Parameters:
      x - the vector.
      Returns:
      the matrix-vector multiplication A' * x.

    • tv

      default void tv(Vector x, Vector y)
      Matrix-vector multiplication A' * x.
      Parameters:
      x - the input vector.
      y - the input and output vector.

    • tv

      default void tv(Vector work, int inputOffset, int outputOffset)
      Matrix-vector multiplication A' * x.
      Parameters:
      work - the workspace for both input and output vector.
      inputOffset - the offset of input vector in workspace.
      outputOffset - the offset of output vector in workspace.

    • mv

      default Vector mv(double[] x)
      Matrix-vector multiplication A * x.
      Parameters:
      x - the vector.
      Returns:
      the matrix-vector multiplication A * x.

    • mv

      default Vector mv(float[] x)
      Matrix-vector multiplication A * x.
      Parameters:
      x - the vector.
      Returns:
      the matrix-vector multiplication A * x.

    • tv

      default Vector tv(double[] x)
      Matrix-vector multiplication A * x.
      Parameters:
      x - the vector.
      Returns:
      the matrix-vector multiplication A * x.

    • tv

      default Vector tv(float[] x)
      Matrix-vector multiplication A * x.
      Parameters:
      x - the vector.
      Returns:
      the matrix-vector multiplication A * x.

    • xAx

      default double xAx(Vector x)
      Returns the quadratic form x' * A * x. The left upper submatrix of A is used in the computation based on the size of x.
      Parameters:
      x - the vector.
      Returns:
      the quadratic form.

    • market

      static Matrix market(Path path) throws IOException, ParseException
      Reads a matrix from a Matrix Market File Format file. For details, see http://people.sc.fsu.edu/~jburkardt/data/mm/mm.html.

      The returned matrix may be dense or sparse.

      Parameters:
      path - the input file path.
      Returns:
      a dense or sparse matrix.
      Throws:
      IOException - when fails to read the file.
      ParseException - when fails to parse the file.