Module math
Package de.lmu.ifi.dbs.elki.math.linearalgebra

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