com.dautelle.math
Class Matrix

java.lang.Object
  com.dautelle.realtime.RealtimeObject
      com.dautelle.math.Matrix

All Implemented Interfaces:

Operable, Realtime, Representable, java.io.Serializable

Direct Known Subclasses:

Vector

public class Matrix

extends RealtimeObject

implements Operable, Representable

This class represents a rectangular array of Operable objects. 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 ConcurrentContext to accelerate calculations on multi-processor systems.

Version:

6.0, May 11, 2004

Author:

Jean-Marie Dautelle

See Also:

Matrix -- from MathWorld, Serialized Form

Nested Class Summary

Nested classes inherited from class com.dautelle.realtime.RealtimeObject

RealtimeObject.Factory

Constructor Summary

protected

Matrix() Default constructor.

Method Summary

Matrix	add(Matrix that) Returns the sum of this matrix with the one specified.
Matrix	adjoint() Returns the adjoint of this matrix.
Operable	cofactor(int i, int j) Returns the cofactor of an element in this matrix.
Operable	determinant() Returns the determinant of this matrix.
Matrix	divide(Matrix 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.
java.lang.Object	export() Exports this object out of the current pool context.
Operable	get(int i, int j) Returns a single element from this matrix.
int	getColumnDimension() Returns the column dimension of this matrix.
Matrix	getMatrix(int[] rows, int[] columns) Returns a sub-matrix composed of the specified rows and columns from this matrix.
Matrix	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	getRowDimension() Returns the row dimension of this matrix.
int	hashCode() Returns a hash code value for this matrix.
Matrix	inverse() Returns the inverse of this matrix.
boolean	isSquare() Indicates if this matrix is square.
LUDecomposition	lu() Returns the LUDecomposition of this Matrix.
Matrix	multiply(Matrix that) Returns the product of this matrix with the one specified.
Matrix	multiply(Operable k) Return the multiplication of this matrix with the specified factor.
Matrix	negate() Returns the negation of this matrix.
static Matrix	newInstance(int n, int m) Returns a n-by-m matrix filled with null elements.
Operable	opposite() Returns the additive inverse of this object.
Operable	plus(Operable that) Returns the sum of this object with the one specified.
Matrix	pow(int exp) Returns this matrix raised at the specified exponent.
Matrix	pseudoInverse() Returns the pseudo-inverse of this matrix.
Operable	reciprocal() Returns the multiplicative inverse of this object.
void	set(int i, int j, Operable element) Sets a single element of this matrix.
Matrix	subtract(Matrix that) Returns the difference between this matrix and the one specified.
Matrix	tensor(Matrix that) Returns the linear algebraic matrix tensor product of this matrix and another.
Operable	times(Operable that) Returns the product of this object with the one specified.
java.lang.Object	toHeap() Moves this object to the heap.
java.lang.String	toString() Returns the text representation of this matrix.
void	toXml(XmlElement xml) Sets the attributes and content of the XML element corresponding to this object.
Operable	trace() Returns the trace of this matrix.
Matrix	transpose() Returns the transpose of this matrix.
static Matrix	valueOf(int n, int m, java.util.Collection elements) Returns a n-by-m matrix populated from the specified collection of Operable objects (rows first).
static Matrix	valueOf(int n, int m, Operable diagonal, Operable other) Returns a n-by-m matrix filled with the specified diagonal element and the specified non-diagonal element.
static Matrix	valueOf(Operable[][] elements) Returns a matrix from a 2-dimensional array of Operable objects.
static Matrix	valueOf(XmlElement xml) XML factory method.

Methods inherited from class com.dautelle.realtime.RealtimeObject

clone, isLocalObject, isPoolObject, recycle

Methods inherited from class java.lang.Object

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

Constructor Detail

Matrix

protected Matrix()

Default constructor.

Method Detail

newInstance

public static Matrix newInstance(int n,
                                 int m)

Returns a n-by-m matrix filled with null elements.

Parameters:

n - the number of rows.

m - the number of columns.

Returns:

a n-by-m matrix non-initialized.

valueOf

public static Matrix valueOf(int n,
                             int m,
                             Operable diagonal,
                             Operable other)

Returns a n-by-m 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(n, n, ONE, ZERO)).

Parameters:

n - the number of rows.

m - the number of columns.

diagonal - the diagonal element.

other - the non-diagonal element.

Returns:

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

valueOf

public static Matrix valueOf(Operable[][] elements)

Returns a matrix from a 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 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 - all rows must have the same length.

valueOf

public static Matrix valueOf(int n,
                             int m,
                             java.util.Collection elements)

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

Parameters:

n - the number of rows.

m - the number of columns.

elements - the collection of Operable objects.

Returns:

the matrix having the specified size and elements.

Throws:

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

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

valueOf

public static Matrix valueOf(XmlElement xml)

XML factory method.

Parameters:

xml - the XML element describing the matrix to return. 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>

Returns:

a new matrix as described by the specified XML element.

getRowDimension

public final int getRowDimension()

Returns the row dimension of this matrix.

Returns:

n, the number of rows.

getColumnDimension

public final int getColumnDimension()

Returns the column dimension of this matrix.

Returns:

m, the number of columns.

isSquare

public final boolean isSquare()

Indicates if this matrix is square.

Returns:

getRowDimension == getColumnDimension

get

public final Operable get(int i,
                          int j)

Returns a single element from this matrix.

Parameters:

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

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

Returns:

the element read at [i,j].

Throws:

java.lang.IndexOutOfBoundsException - i >= getRowDimension() | j >= getColumnDimension().

set

public final void set(int i,
                      int j,
                      Operable element)

Sets a single element of this matrix.

Parameters:

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

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

element - the element set at [i,j].

Throws:

java.lang.IndexOutOfBoundsException - i >= getRowDimension() | j >= getColumnDimension().

getMatrix

public final Matrix 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 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 lu()

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

Returns:

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

equals

public final boolean equals(java.lang.Object that)

Indicates if this matrix is equal to the object specified.

Parameters:

that - the object to compare for equality.

Returns:

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

hashCode

public final int hashCode()

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

Returns:

this matrix hash code value.

See Also:

equals(java.lang.Object)

negate

public final Matrix negate()

Returns the negation of this matrix.

Returns:

-this.

add

public final Matrix add(Matrix that)

Returns the sum of this matrix with the one specified.

Parameters:

that - the matrix to be added.

Returns:

this + that.

Throws:

DimensionException - matrices's dimensions are different.

subtract

public final Matrix subtract(Matrix that)

Returns the difference between this matrix and the one specified.

Parameters:

that - the matrix to be subtracted.

Returns:

this - that.

Throws:

DimensionException - matrices's dimensions are different.

multiply

public final Matrix multiply(Operable k)

Return the multiplication of this matrix with the specified factor.

Parameters:

k - the coefficient multiplier.

Returns:

k * M.

multiply

public Matrix multiply(Matrix that)

Returns the product of this matrix with the one specified.

Note: This method uses ConcurrentContext to reduce garbage and accelerate calculation on multi-processor systems.

Parameters:

that - the matrix multiplier.

Returns:

this * that.

Throws:

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

divide

public Matrix divide(Matrix that)

Returns this matrix divided by the one specified.

Parameters:

that - the matrix divisor.

Returns:

this.multiply(that.inverse()).

pseudoInverse

public Matrix pseudoInverse()

Returns the pseudo-inverse of this matrix. The matrix doesn't need to be square and can be ill-formed. Stability is guaranteed.

Returns:

the pseudo-inverse of this matrix.

inverse

public Matrix inverse()

Returns the inverse of this matrix.

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 this matrix or its pseudoInverse() if the matrix is not square.

See Also:

lu()

tensor

public Matrix tensor(Matrix 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).

toString

public java.lang.String toString()

Returns the text representation of this matrix.

Returns:

the text representation of this matrix.

transpose

public Matrix transpose()

Returns the transpose of this matrix.

Returns:

A'.

determinant

public Operable 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:

DimensionException - matrix is not square.

cofactor

public Operable 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:

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

trace

public Operable trace()

Returns the trace of this matrix.

Returns:

the sum of the diagonal elements.

adjoint

public Matrix 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:

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

pow

public Matrix pow(int exp)

Returns this matrix raised at the specified exponent.

Parameters:

exp - the exponent.

Returns:

thisexp

Throws:

DimensionException - if this matrix is not square.

plus

public Operable plus(Operable that)

Description copied from interface: Operable

Returns the sum of this object with the one specified.

Specified by:

plus in interface Operable

Parameters:

that - the object to be added.

Returns:

this + that.

opposite

public Operable opposite()

Description copied from interface: Operable

Returns the additive inverse of this object. It is the object such as this.plus(this.opposite()) == ZERO, with ZERO being the additive identity.

Specified by:

opposite in interface Operable

Returns:

-this.

times

public Operable times(Operable that)

Description copied from interface: Operable

Returns the product of this object with the one specified.

Specified by:

times in interface Operable

Parameters:

that - the object multiplier.

Returns:

this * that.

reciprocal

public Operable reciprocal()

Description copied from interface: Operable

Returns the multiplicative inverse of this object. It it the object such as this.times(this.reciprocal()) == ONE , with ONE being the multiplicative identity.

Specified by:

reciprocal in interface Operable

Returns:

ONE / this.

toXml

public void toXml(XmlElement xml)

Description copied from interface: Representable

Sets the attributes and content of the XML element corresponding to this object.

Specified by:

toXml in interface Representable

Parameters:

xml - the XML element to set according to this object's desired XML representation.

export

public java.lang.Object export()

Description copied from interface: Realtime

Exports this object out of the current pool context. Realtime members are exported as well (recursion). This method affects only objects belonging to the current pool context. To avoid pool depletion, a "free" object from the outer pool is moved to replace the object being exported.

Specified by:

export in interface Realtime

Overrides:

export in class RealtimeObject

toHeap

public java.lang.Object toHeap()

Description copied from interface: Realtime

Moves this object to the heap. Realtime members are moved to the heap as well (recursion). This method affects only objects belonging to a pool context (current or not).

Specified by:

toHeap in interface Realtime

Overrides:

toHeap in class RealtimeObject