org.apache.commons.math.linear
Class RealMatrixImpl

java.lang.Object
  org.apache.commons.math.linear.RealMatrixImpl

All Implemented Interfaces:

RealMatrix, Serializable

public class RealMatrixImpl

extends Object

implements RealMatrix, Serializable

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

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

• solve
• isSingular
• getDeterminant
• inverse

Usage notes:

• The LU decomposition is cached and reused on subsequent calls. 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.
• As specified in the RealMatrix interface, matrix element indexing is 0-based -- e.g., getEntry(0, 0) returns the element in the first row, first column of the matrix.

Version:

$Revision: 1.35 $ $Date: 2004/11/07 20:19:22 $

See Also:

Serialized Form

Field Summary

(package private) static long	serialVersionUID Serializable version identifier
protected static double	TOO_SMALL Bound to determine effective singularity in LU decomposition

Constructor Summary

RealMatrixImpl()
Creates a matrix with no data

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

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

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

Method Summary

RealMatrix	add(RealMatrix m) Compute the sum of this and m.
RealMatrix	copy() Create a new RealMatrix which is a copy of this.
boolean	equals(Object object) Returns true iff object is a RealMatrixImpl instance with the same dimensions as this and all corresponding matrix entries are equal.
double[]	getColumn(int col) Returns the entries in column number col as an array.
int	getColumnDimension() Returns the number of columns in the matrix.
RealMatrix	getColumnMatrix(int column) Returns the entries in column number column as a column matrix.
double[][]	getData() Returns matrix entries as a two-dimensional array.
double[][]	getDataRef() Returns a reference to the underlying data array.
double	getDeterminant() Returns the determinant of this matrix.
double	getEntry(int row, int column) Returns the entry in the specified row and column.
protected RealMatrix	getIdentity(int dimension) Returns dimension x dimension identity matrix.
protected RealMatrix	getLUMatrix() Returns the LU decomposition as a RealMatrix.
double	getNorm() Returns the maximum absolute row sum norm of the matrix.
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() Returns the number of rows in the matrix.
RealMatrix	getRowMatrix(int row) Returns the entries in row number row as a row matrix.
RealMatrix	getSubMatrix(int[] selectedRows, int[] selectedColumns) Gets a submatrix.
RealMatrix	getSubMatrix(int startRow, int endRow, int startColumn, int endColumn) Gets a submatrix.
double	getTrace() Returns the trace of the matrix (the sum of the elements on the main diagonal).
int	hashCode() Computes a hashcode for the matrix.
RealMatrix	inverse() Returns the inverse matrix if this matrix is invertible.
boolean	isSingular() Is this a singular matrix?
boolean	isSquare() Is this a square matrix?
void	luDecompose() Computes a new LU decompostion for this matrix, storing the result for use by other methods.
RealMatrix	multiply(RealMatrix m) Returns the result of postmultiplying this by m.
double[]	operate(double[] v) Returns the result of multiplying this by the vector v.
double[]	preMultiply(double[] v) Returns the (row) vector result of premultiplying this by the vector v.
RealMatrix	preMultiply(RealMatrix m) Returns the result premultiplying this by m.
RealMatrix	scalarAdd(double d) Returns the result of adding d to each entry of this.
RealMatrix	scalarMultiply(double d) Returns the result multiplying each entry of this by d
double[]	solve(double[] b) Returns a matrix of (column) solution vectors for linear systems with coefficient matrix = this and constant vectors = columns of b.
RealMatrix	solve(RealMatrix b) Returns a matrix of (column) solution vectors for linear systems with coefficient matrix = this and constant vectors = columns of b.
RealMatrix	subtract(RealMatrix m) Compute this minus m.
String	toString()
RealMatrix	transpose() Returns the transpose matrix.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

serialVersionUID

static final long serialVersionUID

Serializable version identifier

See Also:

Constant Field Values

TOO_SMALL

protected static double TOO_SMALL

Bound to determine effective singularity in LU decomposition

Constructor Detail

RealMatrixImpl

public RealMatrixImpl()

Creates a matrix with no data

RealMatrixImpl

public RealMatrixImpl(int rowDimension,
                      int columnDimension)

Create a new RealMatrix 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

RealMatrixImpl

public RealMatrixImpl(double[][] d)

Create a new RealMatrix using the input array as the underlying data array.

The input array is copied, not referenced.

Parameters:

d - data for new matrix

Throws:

IllegalArgumentException - if data is not rectangular (not all rows have the same length) or empty

NullPointerException - if data is null

RealMatrixImpl

public RealMatrixImpl(double[] v)

Create a new (column) RealMatrix 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 RealMatrix copy()

Create a new RealMatrix which is a copy of this.

Specified by:

copy in interface RealMatrix

Returns:

the cloned matrix

add

public RealMatrix add(RealMatrix m)
               throws IllegalArgumentException

Compute the sum of this and m.

Specified by:

add in interface RealMatrix

Parameters:

m - matrix to be added

Returns:

this + m

Throws:

IllegalArgumentException - if m is not the same size as this

subtract

public RealMatrix subtract(RealMatrix m)
                    throws IllegalArgumentException

Compute this minus m.

Specified by:

subtract in interface RealMatrix

Parameters:

m - matrix to be subtracted

Returns:

this + m

Throws:

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

scalarAdd

public RealMatrix scalarAdd(double d)

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

Specified by:

scalarAdd in interface RealMatrix

Parameters:

d - value to be added to each entry

Returns:

d + this

scalarMultiply

public RealMatrix scalarMultiply(double d)

Returns the result multiplying each entry of this by d

Specified by:

scalarMultiply in interface RealMatrix

Parameters:

d - value to multiply all entries by

Returns:

d * this

multiply

public RealMatrix multiply(RealMatrix m)
                    throws IllegalArgumentException

Returns the result of postmultiplying this by m.

Specified by:

multiply in interface RealMatrix

Parameters:

m - matrix to postmultiply by

Returns:

this*m

Throws:

IllegalArgumentException - if columnDimension(this) != rowDimension(m)

preMultiply

public RealMatrix preMultiply(RealMatrix m)
                       throws IllegalArgumentException

Returns the result premultiplying this by m.

Specified by:

preMultiply in interface RealMatrix

Parameters:

m - matrix to premultiply by

Returns:

m * this

Throws:

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.

Specified by:

getData in interface RealMatrix

Returns:

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

getNorm

public double getNorm()

Description copied from interface: RealMatrix

Returns the maximum absolute row sum norm of the matrix.

Specified by:

getNorm in interface RealMatrix

Returns:

norm

getSubMatrix

public RealMatrix getSubMatrix(int startRow,
                               int endRow,
                               int startColumn,
                               int endColumn)
                        throws MatrixIndexException

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

Specified by:

getSubMatrix in interface RealMatrix

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:

MatrixIndexException - if row or column selections are not valid

getSubMatrix

public RealMatrix getSubMatrix(int[] selectedRows,
                               int[] selectedColumns)
                        throws MatrixIndexException

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

Specified by:

getSubMatrix in interface RealMatrix

Parameters:

selectedRows - Array of row indices must be non-empty

selectedColumns - Array of column indices must be non-empty

Returns:

The subMatrix containing the data in the specified rows and columns

Throws:

MatrixIndexException - if supplied row or column index arrays are not valid

getRowMatrix

public RealMatrix getRowMatrix(int row)
                        throws MatrixIndexException

Returns the entries in row number row as a row matrix. Row indices start at 0.

Specified by:

getRowMatrix in interface RealMatrix

Parameters:

row - the row to be fetched

Returns:

row matrix

Throws:

MatrixIndexException - if the specified row index is invalid

getColumnMatrix

public RealMatrix getColumnMatrix(int column)
                           throws MatrixIndexException

Returns the entries in column number column as a column matrix. Column indices start at 0.

Specified by:

getColumnMatrix in interface RealMatrix

Parameters:

column - the column to be fetched

Returns:

column matrix

Throws:

MatrixIndexException - if the specified column index is invalid

getRow

public double[] getRow(int row)
                throws MatrixIndexException

Returns the entries in row number row as an array.

Row indices start at 0. A MatrixIndexException is thrown unless 0 <= row < rowDimension.

Specified by:

getRow in interface RealMatrix

Parameters:

row - the row to be fetched

Returns:

array of entries in the row

Throws:

MatrixIndexException - if the specified row index is not valid

getColumn

public double[] getColumn(int col)
                   throws MatrixIndexException

Returns the entries in column number col as an array.

Column indices start at 0. A MatrixIndexException is thrown unless 0 <= column < columnDimension.

Specified by:

getColumn in interface RealMatrix

Parameters:

col - the column to be fetched

Returns:

array of entries in the column

Throws:

MatrixIndexException - if the specified column index is not valid

getEntry

public double getEntry(int row,
                       int column)
                throws MatrixIndexException

Returns the entry in the specified row and column.

Row and column indices start at 0 and must satisfy

• 0 <= row < rowDimension
• 0 <= column < columnDimension

otherwise a MatrixIndexException is thrown.

Specified by:

getEntry in interface RealMatrix

Parameters:

row - row location of entry to be fetched

column - column location of entry to be fetched

Returns:

matrix entry in row,column

Throws:

MatrixIndexException - if the row or column index is not valid

transpose

public RealMatrix transpose()

Returns the transpose matrix.

Specified by:

transpose in interface RealMatrix

Returns:

transpose matrix

inverse

public RealMatrix inverse()
                   throws InvalidMatrixException

Returns the inverse matrix if this matrix is invertible.

Specified by:

inverse in interface RealMatrix

Returns:

inverse matrix

Throws:

InvalidMatrixException - if this is not invertible

getDeterminant

public double getDeterminant()
                      throws InvalidMatrixException

Description copied from interface: RealMatrix

Returns the determinant of this matrix.

Specified by:

getDeterminant in interface RealMatrix

Returns:

determinant

Throws:

InvalidMatrixException - if matrix is not square

isSquare

public boolean isSquare()

Description copied from interface: RealMatrix

Is this a square matrix?

Specified by:

isSquare in interface RealMatrix

Returns:

true if the matrix is square (rowDimension = columnDimension)

isSingular

public boolean isSingular()

Description copied from interface: RealMatrix

Is this a singular matrix?

Specified by:

isSingular in interface RealMatrix

Returns:

true if the matrix is singular

getRowDimension

public int getRowDimension()

Description copied from interface: RealMatrix

Returns the number of rows in the matrix.

Specified by:

getRowDimension in interface RealMatrix

Returns:

rowDimension

getColumnDimension

public int getColumnDimension()

Description copied from interface: RealMatrix

Returns the number of columns in the matrix.

Specified by:

getColumnDimension in interface RealMatrix

Returns:

columnDimension

getTrace

public double getTrace()
                throws IllegalArgumentException

Description copied from interface: RealMatrix

Returns the trace of the matrix (the sum of the elements on the main diagonal).

Specified by:

getTrace in interface RealMatrix

Returns:

trace

Throws:

IllegalArgumentException - if the matrix is not square

operate

public double[] operate(double[] v)
                 throws IllegalArgumentException

Description copied from interface: RealMatrix

Returns the result of multiplying this by the vector v.

Specified by:

operate in interface RealMatrix

Parameters:

v - vector to operate on

Returns:

resulting vector

Throws:

IllegalArgumentException - if columnDimension != v.length

preMultiply

public double[] preMultiply(double[] v)
                     throws IllegalArgumentException

Description copied from interface: RealMatrix

Returns the (row) vector result of premultiplying this by the vector v.

Specified by:

preMultiply in interface RealMatrix

Parameters:

v - vector to premultiply by

Returns:

resulting matrix

Throws:

IllegalArgumentException - if rowDimension != v.length

solve

public double[] solve(double[] b)
               throws IllegalArgumentException,
                      InvalidMatrixException

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

Specified by:

solve in interface RealMatrix

Parameters:

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

Returns:

solution array

Throws:

IllegalArgumentException - if this.rowDimension != row dimension

InvalidMatrixException - if this matrix is not square or is singular

solve

public RealMatrix solve(RealMatrix b)
                 throws IllegalArgumentException,
                        InvalidMatrixException

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

Specified by:

solve in interface RealMatrix

Parameters:

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

Returns:

matrix of solution vectors

Throws:

IllegalArgumentException - if this.rowDimension != row dimension

InvalidMatrixException - if this matrix is not square or is singular

luDecompose

public void luDecompose()
                 throws 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:

InvalidMatrixException - if the matrix is non-square or singular.

toString

public String toString()

See Also:

Object.toString()

equals

public boolean equals(Object object)

Returns true iff object is a RealMatrixImpl instance with the same dimensions as this and all corresponding matrix entries are equal.

Parameters:

object - the object to test equality against.

Returns:

true if object equals this

hashCode

public int hashCode()

Computes a hashcode for the matrix.

Returns:

hashcode for matrix

getIdentity

protected RealMatrix getIdentity(int dimension)

Returns dimension x dimension identity matrix.

Parameters:

dimension - dimension of identity matrix to generate

Returns:

identity matrix

getLUMatrix

protected RealMatrix getLUMatrix()
                          throws InvalidMatrixException

Returns the LU decomposition as a RealMatrix. 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:

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