commonSense.math.linear
Class Matrix

java.lang.Object
  commonSense.math.linear.Matrix

All Implemented Interfaces:

java.io.Serializable

public class Matrix

extends java.lang.Object

implements java.io.Serializable

This class is based on the Apache.org commons.math package, of to be precise: RleaMatrixImpl
Differences with that class are:

• "0-based" in stead of "1-based" indexing. The RealMatrixImpl tries to be consistent with the mathematical notation and that is often the "1-based" indexing. However, JAVA uses a "0-based" indexing system for their (1d, 2d, etc) arrays and that makes more sense (and less error prone)when using both systems combined. Beyond that, it reduced the computation time of some of the packages I developed.
• No implemented interface with many different methods.

Implementation for Matrix using a double[][] array to store entries and LU decomposition to support linear system solution and inverse.

The LU decomposition is performed as needed, to support the following operations:

• solve
• isSingular
• getDeterminant
• inverse

Usage note :
The LU decomposition is stored and reused on subsequent calls. If matrix data are modified using any of the public setXxx methods, the saved decomposition is discarded. If data are modified via references to the underlying array obtained using getDataRef(), then the stored LU decomposition will not be discarded. In this case, you need to explicitly invoke LUDecompose() to recompute the decomposition before using any of the methods above.

Numbering of the rows and columns is as default for an JAVA array, starting with 0 with the highest value for either row-1 or column-1. This facilitates programming of modules which give back an array to construct subMatrices from the original matrix.

Version:

1.27 (Based on Revision: 1.26 of Commons.math and changed accordingly by Kim van der Linde).

See Also:

Serialized Form

Field Summary

protected static double

TOO_SMALL Bound to determine effective singularity in LU decomposition

Constructor Summary

Matrix()
Creates a matrix with no data

Matrix(double[] v)
Create a new (column) Matrix using v as the data for the unique column of the v.length x 1 matrix created.

Matrix(double[][] d)
Create a new Matrix using the data as the underlying data array.

Matrix(int rowDimension, int columnDimension)
Create a new Matrix with the supplied row and column dimensions.

Method Summary

Matrix	add(Matrix m) Compute the sum of this and m.
double[]	columnMeans() Gives the means of each colums of the matrix.
Matrix	copy() Create a new Matrix which is a copy of this.
double[]	getColumn(int col) Returns the entries in column number col as an array.
int	getColumnDimension()
Matrix	getColumnMatrix(int col) Returns the entries in column number col as a Matrix object.
double[][]	getData() Returns matrix entries as a two-dimensional array.
double[][]	getDataRef() Returns a reference to the underlying data array.
double	getDeterminant()
double	getEntry(int row, int column) Returns the entry in the specified row and column.
protected Matrix	getIdentity(int dimension) Returns dimension x dimension identity matrix.
protected Matrix	getLUMatrix() Returns the LU decomposition as a Matrix.
double	getNorm()
protected int[]	getPermutation() Returns the permutation associated with the lu decomposition.
double[]	getRow(int row) Returns the entries in row number row as an array.
int	getRowDimension()
Matrix	getRowMatrix(int row) Returns the entries in row number row as a Matrix object.
Matrix	getSubMatrix(int[] rows, int[] columns) Get a submatrix.
Matrix	getSubMatrix(int[] rows, int startColumn, int endColumn) Get a submatrix.
Matrix	getSubMatrix(int startRow, int endRow, int[] columns) Get a submatrix.
Matrix	getSubMatrix(int startRow, int endRow, int startColumn, int endColumn) Get a submatrix.
double	getTrace()
Matrix	inverse() Returns the inverse matrix if this matrix is invertible.
boolean	isSingular()
boolean	isSquare()
void	luDecompose() Computes a new LU decompostion for this matrix, storing the result for use by other methods.
Matrix	multiply(Matrix m) Returns the result of postmultiplying this by m.
double[]	operate(double[] v)
double[]	preMultiply(double[] v)
Matrix	preMultiply(Matrix m) Returns the result premultiplying this by m.
double[]	rowMeans() Gives the means of each row of the matrix.
Matrix	scalarAdd(double d) Returns the result of adding d to each entry of this.
Matrix	scalarMultiply(double d) Returns the result multiplying each entry of this by d
void	setData(double[][] inData) Overwrites the underlying data for the matrix with a fresh copy of inData.
void	setDataRef(double[][] inData) Overwrites the underlying data for the matrix with a reference to inData.
void	setEntry(int row, int column, double value) Sets the entry in the specified row and column to the specified value.
double[]	solve(double[] b) Returns a matrix of (column) solution vectors for linear systems with coefficient matrix = this and constant vectors = columns of b.
Matrix	solve(Matrix b) Returns a matrix of (column) solution vectors for linear systems with coefficient matrix = this and constant vectors = columns of b.
Matrix	subtract(Matrix m) Compute this minus m.
java.lang.String	toSquareString()
java.lang.String	toString()
Matrix	transpose() Returns the transpose matrix.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

TOO_SMALL

protected static double TOO_SMALL

Bound to determine effective singularity in LU decomposition

Constructor Detail

Matrix

public Matrix()

Creates a matrix with no data

Matrix

public Matrix(int rowDimension,
              int columnDimension)

Create a new Matrix with the supplied row and column dimensions.

Parameters:

rowDimension - the number of rows in the new matrix

columnDimension - the number of columns in the new matrix

Matrix

public Matrix(double[][] d)

Create a new Matrix using the data as the underlying data array.

The input array is copied, not referenced.

Parameters:

d - data for new matrix

Matrix

public Matrix(double[] v)

Create a new (column) Matrix using v as the data for the unique column of the v.length x 1 matrix created.

The input array is copied, not referenced.

Parameters:

v - column vector holding data for new matrix

Method Detail

copy

public Matrix copy()

Create a new Matrix which is a copy of this.

Returns:

the cloned matrix

add

public Matrix add(Matrix m)
           throws java.lang.IllegalArgumentException

Compute the sum of this and m.

Parameters:

m - matrix to be added

Returns:

this + m

Throws:

java.lang.IllegalArgumentException - if m is not the same size as this

subtract

public Matrix subtract(Matrix m)
                throws java.lang.IllegalArgumentException

Compute this minus m.

Parameters:

m - matrix to be subtracted

Returns:

this + m

Throws:

java.lang.IllegalArgumentException - if m is not the same size as *this

scalarAdd

public Matrix scalarAdd(double d)

Returns the result of adding d to each entry of this.

Parameters:

d - value to be added to each entry

Returns:

d + this

scalarMultiply

public Matrix scalarMultiply(double d)

Returns the result multiplying each entry of this by d

Parameters:

d - value to multiply all entries by

Returns:

d * this

multiply

public Matrix multiply(Matrix m)
                throws java.lang.IllegalArgumentException

Returns the result of postmultiplying this by m.

Parameters:

m - matrix to postmultiply by

Returns:

this*m

Throws:

java.lang.IllegalArgumentException - if columnDimension(this) != rowDimension(m)

preMultiply

public Matrix preMultiply(Matrix m)
                   throws java.lang.IllegalArgumentException

Returns the result premultiplying this by m.

Parameters:

m - matrix to premultiply by

Returns:

m * this

Throws:

java.lang.IllegalArgumentException - if rowDimension(this) != columnDimension(m)

getData

public double[][] getData()

Returns matrix entries as a two-dimensional array.

Makes a fresh copy of the underlying data.

Returns:

2-dimensional array of entries

setData

public void setData(double[][] inData)

Overwrites the underlying data for the matrix with a fresh copy of inData.

Parameters:

inData - 2-dimensional array of entries

getDataRef

public double[][] getDataRef()

Returns a reference to the underlying data array.

Does not make a fresh copy of the underlying data.

Returns:

2-dimensional array of entries

setDataRef

public void setDataRef(double[][] inData)

Overwrites the underlying data for the matrix with a reference to inData.

Does not make a fresh copy of data.

Parameters:

inData - 2-dimensional array of entries

getNorm

public double getNorm()

Returns:

norm

getRow

public double[] getRow(int row)
                throws org.apache.commons.math.linear.MatrixIndexException

Returns the entries in row number row as an array.

Parameters:

row - the row to be fetched

Returns:

array of entries in the row

Throws:

org.apache.commons.math.linear.MatrixIndexException - if the specified row is greater than the number of rows in this matrix

getRowMatrix

public Matrix getRowMatrix(int row)
                    throws org.apache.commons.math.linear.MatrixIndexException

Returns the entries in row number row as a Matrix object.

Parameters:

row - the row to be fetched

Returns:

Matrix with only one row

Throws:

org.apache.commons.math.linear.MatrixIndexException - if the specified row is greater than the number of rows in this matrix

getColumn

public double[] getColumn(int col)
                   throws org.apache.commons.math.linear.MatrixIndexException

Returns the entries in column number col as an array.

Parameters:

col - column to fetch

Returns:

array of entries in the column

Throws:

org.apache.commons.math.linear.MatrixIndexException - if the specified column is greater than the number of columns in this matrix

getColumnMatrix

public Matrix getColumnMatrix(int col)
                       throws org.apache.commons.math.linear.MatrixIndexException

Returns the entries in column number col as a Matrix object.

Parameters:

col - column to fetch

Returns:

Matrix with only one column

Throws:

org.apache.commons.math.linear.MatrixIndexException - if the specified column is greater than the number of columns in this matrix

getEntry

public double getEntry(int row,
                       int column)
                throws org.apache.commons.math.linear.MatrixIndexException

Returns the entry in the specified row and column.

Parameters:

row - row location of entry to be fetched

column - column location of entry to be fetched

Returns:

matrix entry in row,column

Throws:

org.apache.commons.math.linear.MatrixIndexException - if the specified coordinate is outside the dimensions of this matrix

setEntry

public void setEntry(int row,
                     int column,
                     double value)
              throws org.apache.commons.math.linear.MatrixIndexException

Sets the entry in the specified row and column to the specified value.

Parameters:

row - row location of entry to be set

column - column location of entry to be set

value - value to set

Throws:

org.apache.commons.math.linear.MatrixIndexException - if the specified coordinate is outside he dimensions of this matrix

transpose

public Matrix transpose()

Returns the transpose matrix.

Returns:

transpose matrix

inverse

public Matrix inverse()
               throws org.apache.commons.math.linear.InvalidMatrixException

Returns the inverse matrix if this matrix is invertible.

Returns:

inverse matrix

Throws:

org.apache.commons.math.linear.InvalidMatrixException - if this is not invertible

getDeterminant

public double getDeterminant()
                      throws org.apache.commons.math.linear.InvalidMatrixException

Returns:

determinant

Throws:

org.apache.commons.math.linear.InvalidMatrixException - if matrix is not square

isSquare

public boolean isSquare()

Returns:

true if the matrix is square (rowDimension = columnDimension)

isSingular

public boolean isSingular()

Returns:

true if the matrix is singular

getRowDimension

public int getRowDimension()

Returns:

rowDimension

getColumnDimension

public int getColumnDimension()

Returns:

columnDimension

getTrace

public double getTrace()
                throws java.lang.IllegalArgumentException

Returns:

trace

Throws:

java.lang.IllegalArgumentException - if the matrix is not square

operate

public double[] operate(double[] v)
                 throws java.lang.IllegalArgumentException

Parameters:

v - vector to operate on

Returns:

resulting vector

Throws:

java.lang.IllegalArgumentException - if columnDimension != v.length

preMultiply

public double[] preMultiply(double[] v)
                     throws java.lang.IllegalArgumentException

Parameters:

v - vector to premultiply by

Returns:

resulting matrix

Throws:

java.lang.IllegalArgumentException - if rowDimension != v.length

solve

public double[] solve(double[] b)
               throws java.lang.IllegalArgumentException,
                      org.apache.commons.math.linear.InvalidMatrixException

Returns a matrix of (column) solution vectors for linear systems with coefficient matrix = this and constant vectors = columns of b.

Parameters:

b - array of constant forming RHS of linear systems to to solve

Returns:

solution array

Throws:

java.lang.IllegalArgumentException - if this.rowDimension != row dimension

org.apache.commons.math.linear.InvalidMatrixException - if this matrix is not square or is singular

solve

public Matrix solve(Matrix b)
             throws java.lang.IllegalArgumentException,
                    org.apache.commons.math.linear.InvalidMatrixException

Returns a matrix of (column) solution vectors for linear systems with coefficient matrix = this and constant vectors = columns of b.

Parameters:

b - matrix of constant vectors forming RHS of linear systems to to solve

Returns:

matrix of solution vectors

Throws:

java.lang.IllegalArgumentException - if this.rowDimension != row dimension

org.apache.commons.math.linear.InvalidMatrixException - if this matrix is not square or is singular

luDecompose

public void luDecompose()
                 throws org.apache.commons.math.linear.InvalidMatrixException

Computes a new LU decompostion for this matrix, storing the result for use by other methods.

Implementation Note :
Uses Crout's algortithm , with partial pivoting.

Usage Note :
This method should rarely be invoked directly. Its only use is to force recomputation of the LU decomposition when changes have been made to the underlying data using direct array references. Changes made using setXxx methods will trigger recomputation when needed automatically.

Throws:

org.apache.commons.math.linear.InvalidMatrixException - if the matrix is non-square or singular.

rowMeans

public double[] rowMeans()

Gives the means of each row of the matrix.

Returns:

the row means

columnMeans

public double[] columnMeans()

Gives the means of each colums of the matrix.

Returns:

the column means

getSubMatrix

public Matrix getSubMatrix(int startRow,
                           int endRow,
                           int startColumn,
                           int endColumn)
                    throws org.apache.commons.math.linear.MatrixIndexException

Get a submatrix. Rows and columns are indicated counting from 0 to n-1.

Parameters:

startRow - Initial row index

endRow - Final row index

startColumn - Initial column index

endColumn - Final column index

Returns:

The subMatrix containing the data of the specified rows and columns

Throws:

org.apache.commons.math.linear.MatrixIndexException - matrix dimension mismatch

getSubMatrix

public Matrix getSubMatrix(int[] rows,
                           int[] columns)
                    throws org.apache.commons.math.linear.MatrixIndexException

Get a submatrix. Rows and columns are indicated counting from 0 to n-1.

Parameters:

rows - Array of row indices.

columns - Array of column indices.

Returns:

The subMatrix containing the data of the specified rows and columns

Throws:

org.apache.commons.math.linear.MatrixIndexException - matrix dimension mismatch

getSubMatrix

public Matrix getSubMatrix(int startRow,
                           int endRow,
                           int[] columns)
                    throws org.apache.commons.math.linear.MatrixIndexException

Get a submatrix. Rows and columns are indicated counting from 0 to n-1.

Parameters:

startRow - Initial row index

endRow - Final row index

columns - Array of column indices.

Returns:

The subMatrix containing the data of the specified rows and columns

Throws:

org.apache.commons.math.linear.MatrixIndexException - matrix dimension mismatch

getSubMatrix

public Matrix getSubMatrix(int[] rows,
                           int startColumn,
                           int endColumn)
                    throws org.apache.commons.math.linear.MatrixIndexException

Get a submatrix. Rows and columns are indicated counting from 0 to n-1.

Parameters:

rows - Array of row indices.

startColumn - Initial column index

endColumn - Final column index

Returns:

The subMatrix containing the data of the specified rows and columns

Throws:

org.apache.commons.math.linear.MatrixIndexException - matrix dimension mismatch

toSquareString

public java.lang.String toSquareString()

See Also:

Object.toString()

toString

public java.lang.String toString()

See Also:

Object.toString()

getIdentity

protected Matrix getIdentity(int dimension)

Returns dimension x dimension identity matrix.

Parameters:

dimension - dimension of identity matrix to generate

Returns:

identity matrix

getLUMatrix

protected Matrix getLUMatrix()
                      throws org.apache.commons.math.linear.InvalidMatrixException

Returns the LU decomposition as a Matrix. Returns a fresh copy of the cached LU matrix if this has been computed; otherwise the composition is computed and cached for use by other methods. Since a copy is returned in either case, changes to the returned matrix do not affect the LU decomposition property.

The matrix returned is a compact representation of the LU decomposition. Elements below the main diagonal correspond to entries of the "L" matrix; elements on and above the main diagonal correspond to entries of the "U" matrix.

Example:

 
 
      Returned matrix                L                  U
          2  3  1                   1  0  0            2  3  1
          5  4  6                   5  1  0            0  4  6
          1  7  8                   1  7  1            0  0  8
  
 

The L and U matrices satisfy the matrix equation LU = permuteRows(this),
where permuteRows reorders the rows of the matrix to follow the order determined by the permutation property.

Returns:

LU decomposition matrix

Throws:

org.apache.commons.math.linear.InvalidMatrixException - if the matrix is non-square or singular.

getPermutation

protected int[] getPermutation()

Returns the permutation associated with the lu decomposition. The entries of the array represent a permutation of the numbers 0, ... , nRows - 1.

Example: permutation = [1, 2, 0] means current 2nd row is first, current third row is second and current first row is last.

Returns a fresh copy of the array.

Returns:

the permutation