Module math

Class Matrix

java.lang.Object
de.lmu.ifi.dbs.elki.math.linearalgebra.Matrix

public class Matrix extends Object
A two-dimensional matrix class, where the data is stored as two-dimensional array. Implementation note: this class contains various optimizations that theoretically the java hotspot compiler should optimize on its own. However, they do show up a hotspots in the profiler (in cpu=times mode), so it does make a difference at least when optimizing other parts of ELKI.
Author:
Elke Achtert, Erich Schubert
  • Field Details

    • DELTA

      public static final double DELTA
      A small number to handle numbers near 0 as 0.
      See Also:
    • ERR_NOTSQUARE

      public static final String ERR_NOTSQUARE
      Error: matrix not square.
      See Also:
    • ERR_REINDEX

      public static final String ERR_REINDEX
      Error: matrix indexes incorrect
      See Also:
    • ERR_MATRIX_DIMENSIONS

      public static final String ERR_MATRIX_DIMENSIONS
      Error when matrix dimensions do not agree.
      See Also:
    • elements

      protected final double[][] elements
      Array for internal storage of elements.
  • Constructor Details

    • Matrix

      public Matrix(int m, int n)
      Constructs an m-by-n matrix of zeros.
      Parameters:
      m - number of rows
      n - number of columns
    • Matrix

      public Matrix(int m, int n, double s)
      Constructs an m-by-n constant matrix.
      Parameters:
      m - number of rows
      n - number of columns
      s - A scalar value defining the constant value in the matrix
    • Matrix

      public Matrix(double[][] elements)
      Constructs a matrix from a 2-D array.
      Parameters:
      elements - an array of arrays of doubles defining the values of the matrix
      Throws:
      IllegalArgumentException - if not all rows conform in the same length
    • Matrix

      public Matrix(RationalNumber[][] q)
      Constructs a Matrix for a given array of arrays of RationalNumbers.
      Parameters:
      q - an array of arrays of RationalNumbers. q is not checked for consistency (i.e. whether all rows are of equal length)
    • Matrix

      public Matrix(double[] values, int m)
      Construct a matrix from a one-dimensional packed array
      Parameters:
      values - One-dimensional array of doubles, packed by columns (ala Fortran).
      m - Number of rows.
      Throws:
      IllegalArgumentException - Array length must be a multiple of m.
    • Matrix

      public Matrix(Matrix mat)
      Constructor, cloning an existing matrix.
      Parameters:
      mat - Matrix to clone
  • Method Details

    • constructWithCopy

      public static final Matrix constructWithCopy(double[][] A)
      Construct a matrix from a copy of a 2-D array.
      Parameters:
      A - Two-dimensional array of doubles.
      Returns:
      new matrix
      Throws:
      IllegalArgumentException - All rows must have the same length
    • unitMatrix

      public static final Matrix unitMatrix(int dim)
      Returns the unit matrix of the specified dimension.
      Parameters:
      dim - the dimensionality of the unit matrix
      Returns:
      the unit matrix of the specified dimension
    • zeroMatrix

      public static final Matrix zeroMatrix(int dim)
      Returns the zero matrix of the specified dimension.
      Parameters:
      dim - the dimensionality of the unit matrix
      Returns:
      the zero matrix of the specified dimension
    • random

      public static final Matrix random(int m, int n)
      Generate matrix with random elements
      Parameters:
      m - Number of rows.
      n - Number of columns.
      Returns:
      An m-by-n matrix with uniformly distributed random elements.
    • identity

      public static final Matrix identity(int m, int n)
      Generate identity matrix
      Parameters:
      m - Number of rows.
      n - Number of columns.
      Returns:
      An m-by-n matrix with ones on the diagonal and zeros elsewhere.
    • diagonal

      public static final Matrix diagonal(double[] diagonal)
      Returns a quadratic Matrix consisting of zeros and of the given values on the diagonal.
      Parameters:
      diagonal - the values on the diagonal
      Returns:
      the resulting matrix
    • diagonal

      public static final Matrix diagonal(Vector diagonal)
      Returns a quadratic Matrix consisting of zeros and of the given values on the diagonal.
      Parameters:
      diagonal - the values on the diagonal
      Returns:
      the resulting matrix
    • copy

      public final Matrix copy()
      Make a deep copy of a matrix.
      Returns:
      a new matrix containing the same values as this matrix
    • clone

      public Matrix clone()
      Clone the Matrix object.
      Overrides:
      clone in class Object
    • getArrayRef

      public final double[][] getArrayRef()
      Access the internal two-dimensional array.
      Returns:
      Pointer to the two-dimensional array of matrix elements.
    • getArrayCopy

      public final double[][] getArrayCopy()
      Copy the internal two-dimensional array.
      Returns:
      Two-dimensional array copy of matrix elements.
    • getRowDimensionality

      public final int getRowDimensionality()
      Returns the dimensionality of the rows of this matrix.
      Returns:
      m, the number of rows.
    • getColumnDimensionality

      public final int getColumnDimensionality()
      Returns the dimensionality of the columns of this matrix.
      Returns:
      n, the number of columns.
    • get

      public final double get(int i, int j)
      Get a single element.
      Parameters:
      i - Row index.
      j - Column index.
      Returns:
      A(i,j)
      Throws:
      ArrayIndexOutOfBoundsException - on bounds error
    • set

      public final Matrix set(int i, int j, double s)
      Set a single element.
      Parameters:
      i - Row index.
      j - Column index.
      s - A(i,j).
      Returns:
      modified matrix
      Throws:
      ArrayIndexOutOfBoundsException - on bounds error
    • increment

      public final Matrix increment(int i, int j, double s)
      Increments a single element.
      Parameters:
      i - the row index
      j - the column index
      s - the increment value: A(i,j) = A(i.j) + s.
      Returns:
      modified matrix
      Throws:
      ArrayIndexOutOfBoundsException - on bounds error
    • getRowPackedCopy

      public final double[] getRowPackedCopy()
      Make a one-dimensional row packed copy of the internal array.
      Returns:
      Matrix elements packed in a one-dimensional array by rows.
    • getColumnPackedCopy

      public final double[] getColumnPackedCopy()
      Make a one-dimensional column packed copy of the internal array.
      Returns:
      Matrix elements packed in a one-dimensional array by columns.
    • getMatrix

      public final Matrix getMatrix(int i0, int i1, int j0, int j1)
      Get a submatrix.
      Parameters:
      i0 - Initial row index
      i1 - Final row index
      j0 - Initial column index
      j1 - Final column index
      Returns:
      A(i0:i1,j0:j1)
      Throws:
      ArrayIndexOutOfBoundsException - Submatrix indices
    • getMatrix

      public final Matrix getMatrix(int[] r, int[] c)
      Get a submatrix.
      Parameters:
      r - Array of row indices.
      c - Array of column indices.
      Returns:
      A(r(:),c(:))
      Throws:
      ArrayIndexOutOfBoundsException - Submatrix indices
    • getMatrix

      public final Matrix getMatrix(int[] r, int j0, int j1)
      Get a submatrix.
      Parameters:
      r - Array of row indices.
      j0 - Initial column index
      j1 - Final column index
      Returns:
      A(r(:),j0:j1)
      Throws:
      ArrayIndexOutOfBoundsException - Submatrix indices
    • getMatrix

      public final Matrix getMatrix(int i0, int i1, int[] c)
      Get a submatrix.
      Parameters:
      i0 - Initial row index
      i1 - Final row index
      c - Array of column indices.
      Returns:
      A(i0:i1,c(:))
      Throws:
      ArrayIndexOutOfBoundsException - Submatrix indices
    • setMatrix

      public final void setMatrix(int i0, int i1, int j0, int j1, Matrix X)
      Set a submatrix.
      Parameters:
      i0 - Initial row index
      i1 - Final row index
      j0 - Initial column index
      j1 - Final column index
      X - A(i0:i1,j0:j1)
      Throws:
      ArrayIndexOutOfBoundsException - Submatrix indices
    • setMatrix

      public final void setMatrix(int[] r, int[] c, Matrix X)
      Set a submatrix.
      Parameters:
      r - Array of row indices.
      c - Array of column indices.
      X - A(r(:),c(:))
      Throws:
      ArrayIndexOutOfBoundsException - Submatrix indices
    • setMatrix

      public final void setMatrix(int[] r, int j0, int j1, Matrix X)
      Set a submatrix.
      Parameters:
      r - Array of row indices.
      j0 - Initial column index
      j1 - Final column index
      X - A(r(:),j0:j1)
      Throws:
      ArrayIndexOutOfBoundsException - Submatrix indices
    • setMatrix

      public final void setMatrix(int i0, int i1, int[] c, Matrix X)
      Set a submatrix.
      Parameters:
      i0 - Initial row index
      i1 - Final row index
      c - Array of column indices.
      X - A(i0:i1,c(:))
      Throws:
      ArrayIndexOutOfBoundsException - Submatrix indices
    • getRow

      public final Vector getRow(int i)
      Returns the ith row of this matrix as vector.
      Parameters:
      i - the index of the row to be returned
      Returns:
      the ith row of this matrix
    • setRow

      public final void setRow(int j, Vector row)
      Sets the jth row of this matrix to the specified vector.
      Parameters:
      j - the index of the column to be set
      row - the value of the column to be set
    • getCol

      public final Vector getCol(int j)
      Returns the jth column of this matrix as vector.
      Parameters:
      j - the index of the column to be returned
      Returns:
      the jth column of this matrix
    • setCol

      public final void setCol(int j, Vector column)
      Sets the jth column of this matrix to the specified column.
      Parameters:
      j - the index of the column to be set
      column - the value of the column to be set
    • transpose

      public final Matrix transpose()
      Matrix transpose.
      Returns:
      AT
    • plus

      public final Matrix plus(Matrix B)
      C = A + B
      Parameters:
      B - another matrix
      Returns:
      A + B in a new Matrix
    • plusTimes

      public final Matrix plusTimes(Matrix B, double s)
      C = A + s * B
      Parameters:
      B - another matrix
      s - scalar
      Returns:
      A + s * B in a new Matrix
    • plusEquals

      public final Matrix plusEquals(Matrix B)
      A = A + B
      Parameters:
      B - another matrix
      Returns:
      A + B in this Matrix
    • plusTimesEquals

      public final Matrix plusTimesEquals(Matrix B, double s)
      A = A + s * B
      Parameters:
      B - another matrix
      s - Scalar
      Returns:
      A + s * B in this Matrix
    • minus

      public final Matrix minus(Matrix B)
      C = A - B
      Parameters:
      B - another matrix
      Returns:
      A - B in a new Matrix
    • minusTimes

      public final Matrix minusTimes(Matrix B, double s)
      C = A - s * B
      Parameters:
      B - another matrix
      s - Scalar
      Returns:
      A - s * B in a new Matrix
    • minusEquals

      public final Matrix minusEquals(Matrix B)
      A = A - B
      Parameters:
      B - another matrix
      Returns:
      A - B in this Matrix
    • minusTimesEquals

      public final Matrix minusTimesEquals(Matrix B, double s)
      A = A - s * B
      Parameters:
      B - another matrix
      s - Scalar
      Returns:
      A - s * B in this Matrix
    • times

      public final Matrix times(double s)
      Multiply a matrix by a scalar, C = s*A
      Parameters:
      s - scalar
      Returns:
      s*A
    • timesEquals

      public final Matrix timesEquals(double s)
      Multiply a matrix by a scalar in place, A = s*A
      Parameters:
      s - scalar
      Returns:
      replace A by s*A
    • times

      public final Matrix times(Matrix B)
      Linear algebraic matrix multiplication, A * B
      Parameters:
      B - another matrix
      Returns:
      Matrix product, A * B
      Throws:
      IllegalArgumentException - Matrix inner dimensions must agree.
    • times

      public final Vector times(Vector B)
      Linear algebraic matrix multiplication, A * B
      Parameters:
      B - a vector
      Returns:
      Matrix product, A * B
      Throws:
      IllegalArgumentException - Matrix inner dimensions must agree.
    • transposeTimes

      public final Vector transposeTimes(Vector B)
      Linear algebraic matrix multiplication, AT * B
      Parameters:
      B - another matrix
      Returns:
      Matrix product, AT * B
      Throws:
      IllegalArgumentException - Matrix inner dimensions must agree.
    • transposeTimes

      public final Matrix transposeTimes(Matrix B)
      Linear algebraic matrix multiplication, AT * B
      Parameters:
      B - another matrix
      Returns:
      Matrix product, AT * B
      Throws:
      IllegalArgumentException - Matrix inner dimensions must agree.
    • timesTranspose

      public final Matrix timesTranspose(Matrix B)
      Linear algebraic matrix multiplication, A * B^T
      Parameters:
      B - another matrix
      Returns:
      Matrix product, A * B^T
      Throws:
      IllegalArgumentException - Matrix inner dimensions must agree.
    • transposeTimesTranspose

      public final Matrix transposeTimesTranspose(Matrix B)
      Linear algebraic matrix multiplication, A^T * B^T. Computed as (B*A)^T
      Parameters:
      B - another matrix
      Returns:
      Matrix product, A^T * B^T
      Throws:
      IllegalArgumentException - Matrix inner dimensions must agree.
    • solve

      public final Matrix solve(Matrix B)
      Solve A*X = B
      Parameters:
      B - right hand side
      Returns:
      solution if A is square, least squares solution otherwise
    • inverse

      public final Matrix inverse()
      Matrix inverse or pseudoinverse
      Returns:
      inverse(A) if A is square, pseudoinverse otherwise.
    • det

      public final double det()
      Matrix determinant
      Returns:
      determinant
    • rank

      public final int rank()
      Matrix rank
      Returns:
      effective numerical rank, obtained from SVD.
    • cond

      public final double cond()
      Matrix condition (2 norm)
      Returns:
      ratio of largest to smallest singular value.
    • trace

      public final double trace()
      Matrix trace.
      Returns:
      sum of the diagonal elements.
    • norm1

      public final double norm1()
      One norm
      Returns:
      maximum column sum.
    • norm2

      public final double norm2()
      Two norm
      Returns:
      maximum singular value.
    • normInf

      public final double normInf()
      Infinity norm
      Returns:
      maximum row sum.
    • normF

      public final double normF()
      Frobenius norm
      Returns:
      sqrt of sum of squares of all elements.
    • normalizeColumns

      public final void normalizeColumns()
      Normalizes the columns of this matrix to length of 1.0.
    • exactGaussJordanElimination

      public final Matrix exactGaussJordanElimination()
      Returns a matrix derived by Gauss-Jordan-elimination using RationalNumbers for the transformations.
      Returns:
      a matrix derived by Gauss-Jordan-elimination using RationalNumbers for the transformations
    • isSymmetric

      public final boolean isSymmetric()
      Returns true, if this matrix is symmetric, false otherwise.
      Returns:
      true, if this matrix is symmetric, false otherwise
    • appendColumns

      public final Matrix appendColumns(Matrix columns)
      Returns a matrix which consists of this matrix and the specified columns.
      Parameters:
      columns - the columns to be appended
      Returns:
      the new matrix with the appended columns
    • orthonormalize

      public final Matrix orthonormalize()
      Returns an orthonormalization of this matrix.
      Returns:
      the orthonormalized matrix
    • cheatToAvoidSingularity

      public final Matrix cheatToAvoidSingularity(double constant)
      Adds a given value to the diagonal entries if the entry is smaller than the constant.
      Parameters:
      constant - value to add to the diagonal entries
      Returns:
      a new Matrix differing from this Matrix by the given value added to the diagonal entries
    • checkMatrixDimensions

      protected void checkMatrixDimensions(Matrix B)
      Check if size(A) == size(B)
    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object
    • almostEquals

      public boolean almostEquals(Object obj, double maxdelta)
      Compare two matrices with a delta parameter to take numerical errors into account.
      Parameters:
      obj - other object to compare with
      maxdelta - maximum delta allowed
      Returns:
      true if delta smaller than maximum
    • almostEquals

      public boolean almostEquals(Object obj)
      Compare two matrices with a delta parameter to take numerical errors into account.
      Parameters:
      obj - other object to compare with
      Returns:
      almost equals with delta DELTA
    • toString

      public String toString()
      toString returns String-representation of Matrix.
      Overrides:
      toString in class Object