org.jscience.mathematics.matrices
Class Matrix<O extends Operable<O>>

java.lang.Object
  javolution.realtime.RealtimeObject
      org.jscience.mathematics.matrices.Matrix<O>

All Implemented Interfaces:

java.io.Serializable, Realtime, Operable<Matrix<O>>

Direct Known Subclasses:

Vector

public class Matrix<O extends Operable<O>>
extends RealtimeObject
implements Operable<Matrix<O>>, java.io.Serializable

This class represents an immutable matrix of Operable elements. It may be used to resolve system of linear equations involving any kind of Operable elements (e.g. Real, Complex, Quantity, Function, etc).

Non-commutative multiplication is supported and this class itself implements the Operable interface. Consequently, this class may be used to resolve system of linear equations involving matrices (for which the multiplication is not commutative).

Implementation Note: This class uses concurrent contexts to accelerate calculations on multi-processor systems.

Version:

2.0, June 6, 2004

Author:

Jean-Marie Dautelle

See Also:

Matrix -- from MathWorld, Serialized Form

Nested Class Summary

Nested classes/interfaces inherited from class javolution.realtime.RealtimeObject

RealtimeObject.Factory<T extends RealtimeObject>

Nested classes/interfaces inherited from interface javolution.realtime.Realtime

Realtime.ObjectSpace

Field Summary

protected static XmlFormat<Matrix>

XML Holds the default XML representation for Matrix and its sub-classes.

Constructor Summary

Matrix(O[][] elements)
Creates a matrix from the specified 2-dimensional array of Operable objects.

Method Summary

Matrix<O>	adjoint() Returns the adjoint of this matrix.
O	cofactor(int i, int j) Returns the cofactor of an element in this matrix.
O	determinant() Returns the determinant of this matrix.
Matrix<O>	divide(Matrix<O> that) Returns this matrix divided by the one specified.
boolean	equals(java.lang.Object that) Indicates if this matrix is equal to the object specified.
O	get(int i, int j) Returns a single element from this matrix.
Matrix<O>	getMatrix(int[] rows, int[] columns) Returns a sub-matrix composed of the specified rows and columns from this matrix.
Matrix<O>	getMatrix(int i0, int i1, int j0, int j1) Returns a sub-matrix of this matrix given the range of its rows and columns indices.
int	getNumberOfColumns() Returns the number of columns for this matrix.
int	getNumberOfRows() Returns the number of rows for this matrix.
int	hashCode() Returns a hash code value for this matrix.
Matrix<O>	inverse() Returns the inverse or pseudo-inverse if this matrix if not square.
boolean	isSquare() Indicates if this matrix is square.
LUDecomposition<O>	lu() Returns the LUDecomposition of this Matrix.
Matrix<O>	minus(Matrix<O> that) Returns the difference between this matrix and the one specified.
boolean	move(Realtime.ObjectSpace os)
Matrix<O>	opposite() Returns the negation of this matrix.
Matrix<O>	plus(Matrix<O> that) Returns the sum of this matrix with the one specified.
Matrix<O>	pow(int exp) Returns this matrix raised at the specified exponent.
Matrix<O>	reciprocal() Returns the reciprocal of this matrix (must be square).
Matrix<O>	tensor(Matrix<O> that) Returns the linear algebraic matrix tensor product of this matrix and another.
Matrix<O>	times(Matrix<O> that) Returns the product of this matrix with the one specified.
Matrix<O>	times(O k) Return the product of this matrix with the specified factor.
Text	toText() Returns the text representation of this matrix.
O	trace() Returns the trace of this matrix.
Matrix<O>	transpose() Returns the transpose of this matrix.
static Matrix<Float64>	valueOf(double[][] values) Returns a matrix from a 2-dimensional array of double values (convenience method).
static <O extends Operable<O>> Matrix<O>	valueOf(int m, int n, java.util.Collection<O> elements) Returns a m-by-n matrix populated from the specified collection of Operable objects (rows first).
static <O extends Operable<O>> Matrix<O>	valueOf(int m, int n, O diagonal, O other) Returns a m-by-n matrix filled with the specified diagonal element and the specified non-diagonal element.
static <O extends Operable<O>> Matrix<O>	valueOf(O[][] elements) Returns a matrix from a 2-dimensional array of Operable objects.

Methods inherited from class javolution.realtime.RealtimeObject

export, moveHeap, preserve, recycle, toString, unpreserve

Methods inherited from class java.lang.Object

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

Field Detail

XML

protected static final XmlFormat<Matrix> XML

Holds the default XML representation for Matrix and its sub-classes. This representation consists of the matrix elements as nested XML elements and the matrix row and column as attributes. For example:

    <math:Matrix row="2" column="1">
      <math:Complex real="1.0" imaginary="0.0"/>
      <math:Complex real="0.0" imaginary="1.0"/>
    </math:Matrix>

Constructor Detail

Matrix

public Matrix(O[][] elements)

Creates a matrix from the specified 2-dimensional array of Operable objects. The first dimension being the row and the second being the column.

Note: It is safe to reuse the specified array as it is not internally referenced by the matrix being returned.

Parameters:

elements - the array of Operable elements.

Throws:

java.lang.IllegalArgumentException - if rows have different length.

Method Detail

valueOf

public static <O extends Operable<O>> Matrix<O> valueOf(int m,
                                                        int n,
                                                        O diagonal,
                                                        O other)

Returns a m-by-n matrix filled with the specified diagonal element and the specified non-diagonal element. This constructor may be used to create an identity matrix (e.g. valueOf(m, m, ONE, ZERO)).

Parameters:

m - the number of rows.

n - the number of columns.

diagonal - the diagonal element.

other - the non-diagonal element.

Returns:

a m-by-n matrix with d on the diagonal and o elsewhere.

valueOf

public static Matrix<Float64> valueOf(double[][] values)

Returns a matrix from a 2-dimensional array of double values (convenience method). The first dimension being the number of rows and the second being the number of columns ([m,n]).

Parameters:

values - the array of double values.

Returns:

the corresponding matrix of Float64 elements.

Throws:

java.lang.IllegalArgumentException - if rows have different length.

valueOf

public static <O extends Operable<O>> Matrix<O> valueOf(O[][] elements)

Returns a matrix from a 2-dimensional array of Operable objects. The first dimension being the number of rows and the second being the number of columns ([m,n]).

Note: It is safe to reuse the specifed array as it is not internally referenced by the matrix being returned.

Parameters:

elements - the array of Operable objects.

Returns:

the matrix having the specified components.

Throws:

java.lang.IllegalArgumentException - if rows have different length.

valueOf

public static <O extends Operable<O>> Matrix<O> valueOf(int m,
                                                        int n,
                                                        java.util.Collection<O> elements)

Returns a m-by-n matrix populated from the specified collection of Operable objects (rows first).

Parameters:

m - the number of rows.

n - the number of columns.

elements - the collection of Operable objects.

Returns:

the matrix having the specified size and elements.

Throws:

MatrixException - if elements.size() != m * n

java.lang.ClassCastException - if any of the element is not Operable.

getNumberOfRows

public final int getNumberOfRows()

Returns the number of rows for this matrix.

Returns:

m, the number of rows.

getNumberOfColumns

public final int getNumberOfColumns()

Returns the number of columns for this matrix.

Returns:

n, the number of columns.

isSquare

public final boolean isSquare()

Indicates if this matrix is square.

Returns:

nbrOfRows() == nbrOfColumns()

get

public final O get(int i,
                   int j)

Returns a single element from this matrix.

Parameters:

i - the row index (range [0..m[).

j - the column index (range [0..n[).

Returns:

the element read at [i,j].

Throws:

java.lang.IndexOutOfBoundsException - (i < 0) || (i >= m)) || (j < 0) || (j >= n))

getMatrix

public final Matrix<O> getMatrix(int i0,
                                 int i1,
                                 int j0,
                                 int j1)

Returns a sub-matrix of this matrix given the range of its rows and columns indices.

Parameters:

i0 - the initial row index.

i1 - the final row index.

j0 - the initial column index.

j1 - the final column index.

Returns:

THIS(i0:i1, j0:j1)

getMatrix

public final Matrix<O> getMatrix(int[] rows,
                                 int[] columns)

Returns a sub-matrix composed of the specified rows and columns from this matrix.

Parameters:

rows - the indices of the rows to return.

columns - the indices of the columns to return.

Returns:

the sub-matrix from the specified rows and columns.

lu

public final LUDecomposition<O> lu()

Returns the LUDecomposition of this Matrix. Numerical stability is guaranteed (through pivoting) if the Operable elements of this matrix are derived from Numeric. For others elements types, numerical stability can be ensured by setting a local pivot comparator.

Returns:

the decomposition of this matrix into a product of upper and lower triangular matrices.

equals

public boolean equals(java.lang.Object that)

Indicates if this matrix is equal to the object specified.

Overrides:

equals in class java.lang.Object

Parameters:

that - the object to compare for equality.

Returns:

true if this matrix and the specified object are considered equal; false otherwise.

hashCode

public int hashCode()

Returns a hash code value for this matrix. Equals object have equal hash codes.

Overrides:

hashCode in class java.lang.Object

Returns:

this matrix hash code value.

See Also:

equals(java.lang.Object)

opposite

public Matrix<O> opposite()

Returns the negation of this matrix.

Specified by:

opposite in interface Operable<Matrix<O extends Operable<O>>>

Returns:

-this.

plus

public Matrix<O> plus(Matrix<O> that)

Returns the sum of this matrix with the one specified.

Specified by:

plus in interface Operable<Matrix<O extends Operable<O>>>

Parameters:

that - the matrix to be added.

Returns:

this + that.

Throws:

MatrixException - matrices's dimensions are different.

minus

public Matrix<O> minus(Matrix<O> that)

Returns the difference between this matrix and the one specified.

Parameters:

that - the matrix to be subtracted.

Returns:

this - that.

Throws:

MatrixException - matrices's dimensions are different.

times

public Matrix<O> times(O k)

Return the product of this matrix with the specified factor.

Parameters:

k - the coefficient multiplier.

Returns:

k * M.

times

public Matrix<O> times(Matrix<O> that)

Returns the product of this matrix with the one specified.

Specified by:

times in interface Operable<Matrix<O extends Operable<O>>>

Parameters:

that - the matrix multiplier.

Returns:

this * that.

Throws:

MatrixException - M.getRowDimension() != this.getColumnDimension().

divide

public Matrix<O> divide(Matrix<O> that)

Returns this matrix divided by the one specified.

Parameters:

that - the matrix divisor.

Returns:

this / that.

Throws:

MatrixException - if that matrix is not square or dimensions do not match.

reciprocal

public Matrix<O> reciprocal()

Returns the reciprocal of this matrix (must be square).

Specified by:

reciprocal in interface Operable<Matrix<O extends Operable<O>>>

Returns:

1 / this

Throws:

MatrixException - if this matrix is not square.

See Also:

lu()

inverse

public Matrix<O> inverse()

Returns the inverse or pseudo-inverse if this matrix if not square.

Note: To resolve the equation A * X = B, it is usually faster to calculate A.lu().solve(B) rather than A.inverse().times(B).

Returns:

the inverse or pseudo-inverse of this matrix.

See Also:

lu()

tensor

public Matrix<O> tensor(Matrix<O> that)

Returns the linear algebraic matrix tensor product of this matrix and another.

Parameters:

that - the second matrix.

Returns:

the Kronecker Tensor (direct) product of this and that.

Since:

January 2002, by Jonathan Grattage (jjg99c@cs.nott.ac.uk).

toText

public Text toText()

Returns the text representation of this matrix.

Specified by:

toText in interface Realtime

Overrides:

toText in class RealtimeObject

Returns:

the text representation of this matrix.

transpose

public Matrix<O> transpose()

Returns the transpose of this matrix.

Returns:

A'.

determinant

public O determinant()

Returns the determinant of this matrix. This method uses the matrix LU decomposition to guarantee correct results even for non-commutative operables (the famous formula: a00·a11-a10·a01 for 2x2 matrices is incorrect when operables are non-commutative).

Returns:

lu().determinant()

Throws:

MatrixException - matrix is not square.

cofactor

public O cofactor(int i,
                  int j)

Returns the cofactor of an element in this matrix. It is the value obtained by evaluating the determinant formed by the elements not in that particular row or column.

Parameters:

i - the row index.

j - the column index.

Returns:

the cofactor of THIS[i,j].

Throws:

MatrixException - matrix is not square or its dimension is less than 2.

trace

public O trace()

Returns the trace of this matrix.

Returns:

the sum of the diagonal elements.

adjoint

public Matrix<O> adjoint()

Returns the adjoint of this matrix. It is obtained by replacing each element in this matrix with its cofactor and applying a + or - sign according (-1)**(i+j), and then finding the transpose of the resulting matrix.

Returns:

the adjoint of this matrix.

Throws:

MatrixException - if this matrix is not square or if its dimension is less than 2.

pow

public Matrix<O> pow(int exp)

Returns this matrix raised at the specified exponent.

Parameters:

exp - the exponent.

Returns:

thisexp

Throws:

MatrixException - if this matrix is not square.

move

public boolean move(Realtime.ObjectSpace os)

Specified by:

move in interface Realtime

Overrides:

move in class RealtimeObject