org.jscience.mathematics.vectors
Class Matrix<F extends Field<F>>

java.lang.Object
  javolution.context.RealtimeObject
      org.jscience.mathematics.vectors.Matrix<F>

All Implemented Interfaces:

java.io.Serializable, Realtime, Immutable, GroupAdditive<Matrix<F>>, Ring<Matrix<F>>, Structure<Matrix<F>>, VectorSpace<Matrix<F>,F>

Direct Known Subclasses:

ComplexMatrix, DenseMatrix, Float64Matrix, SparseMatrix

public abstract class Matrix<F extends Field<F>>
extends RealtimeObject
implements VectorSpace<Matrix<F>,F>, Ring<Matrix<F>>, Immutable

This class represents a rectangular table of elements of a ring-like algebraic structure.

Instances of this class can be used to resolve system of linear equations involving any kind of Field elements (e.g. Real, Complex, Measure<?>, Function, etc). For example:

        // Creates a dense matrix (2x2) of Rational numbers.
        DenseMatrix<Rational> M = DenseMatrix.valueOf(
            { Rational.valueOf(23, 45), Rational.valueOf(33, 75) },
            { Rational.valueOf(15, 31), Rational.valueOf(-20, 45)});
            
        // Creates a sparse matrix (16x2) of Real numbers.
        SparseMatrix<Real> M = SparseMatrix.valueOf(
            SparseVector.valueOf(16, Real.ZERO, 0, Real.valueOf(5)),
            SparseVector.valueOf(16, Real.ZERO, 15, Real.valueOf(-3)));
            
        // Creates a floating-point (64 bits) matrix (3x2).
        Float64Matrix M = Float64Matrix.valueOf(
           {{ 1.0, 2.0, 3.0}, { 4.0, 5.0, 6.0}});
            
        // Creates a complex single column matrix (1x2).
        ComplexMatrix M = ComplexMatrix.valueOf(
           {{ Complex.valueOf(1.0, 2.0), Complex.valueOf(4.0, 5.0)}}).transpose();
            
        // Creates an identity matrix (2x2) for modulo integer.
        SparseMatrix<ModuloInteger> IDENTITY = SparseMatrix.valueOf(
           DenseVector.valueOf(ModuloInteger.ONE, ModuloInteger.ONE), ModuloInteger.ZERO);
     

Non-commutative field multiplication is supported. Invertible square matrices may form a non-commutative field (also called a division ring). In which case this class may be used to resolve system of linear equations with matrix coefficients.

Implementation Note: Matrices may use PoolContext and ConcurrentContext in order to minimize heap allocation and accelerate calculations on multi-core systems.

Version:

3.3, December 24, 2006

Author:

Jean-Marie Dautelle

See Also:

Wikipedia: Matrix (mathematics), Serialized Form

Nested Class Summary

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

RealtimeObject.Factory<T extends RealtimeObject>

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

Realtime.ObjectSpace

Field Summary

protected static XMLFormat<Matrix>

XML Holds the default XML representation for matrices.

Constructor Summary

protected

Matrix() Default constructor (for sub-classes).

Method Summary

abstract Matrix<F>	adjoint() Returns the adjoint of this matrix.
abstract F	cofactor(int i, int j) Returns the cofactor of an element in this matrix.
abstract F	determinant() Returns the determinant of this matrix.
Matrix<F>	divide(Matrix<F> that) Returns this matrix divided by the one specified.
boolean	equals(Matrix<F> that, java.util.Comparator<F> cmp) Indicates if this matrix can be considered equals to the one specified using the specified comparator when testing for element equality.
boolean	equals(java.lang.Object that) Indicates if this matrix is strictly equal to the object specified.
abstract F	get(int i, int j) Returns a single element from this matrix.
abstract Vector<F>	getColumn(int j) Returns the column identified by the specified index in this matrix.
abstract Vector<F>	getDiagonal() Returns the diagonal vector.
abstract int	getNumberOfColumns() Returns the number of columns n for this matrix.
abstract int	getNumberOfRows() Returns the number of rows m for this matrix.
abstract Vector<F>	getRow(int i) Returns the row identified by the specified index in this matrix.
int	hashCode() Returns a hash code value for this matrix.
abstract Matrix<F>	inverse() Returns the inverse of this matrix (must be square).
boolean	isSquare() Indicates if this matrix is square.
Matrix<F>	minus(Matrix<F> that) Returns the difference between this matrix and the one specified.
abstract Matrix<F>	opposite() Returns the negation of this matrix.
abstract Matrix<F>	plus(Matrix<F> that) Returns the sum of this matrix with the one specified.
Matrix<F>	pow(int exp) Returns this matrix raised at the specified exponent.
Matrix<F>	pseudoInverse() Returns the inverse or pseudo-inverse if this matrix if not square.
Matrix<F>	solve(Matrix<F> y) Solves this matrix for the specified matrix (returns x such as this · x = y).
Vector<F>	solve(Vector<F> y) Solves this matrix for the specified vector (returns x such as this · x = y).
abstract Matrix<F>	tensor(Matrix<F> that) Returns the linear algebraic matrix tensor product of this matrix and another (Kronecker product).
abstract Matrix<F>	times(F k) Returns the product of this matrix by the specified factor.
abstract Matrix<F>	times(Matrix<F> that) Returns the product of this matrix with the one specified.
abstract Vector<F>	times(Vector<F> v) Returns the product of this matrix by the specified vector.
Text	toText() Returns the text representation of this matrix.
F	trace() Returns the trace of this matrix.
abstract Matrix<F>	transpose() Returns the transpose of this matrix.
static Matrix<Complex>	valueOf(Complex[][] elements) Deprecated. Since 3.3 - Replaced by ComplexMatrix.valueOf(Complex[][])
static Matrix<Float64>	valueOf(double[][] values) Deprecated. Since 3.3 - Replaced by Float64Matrix.valueOf(double[][])
static <F extends Field<F>> Matrix<F>	valueOf(F[][] elements) Deprecated. Since 3.3 - Replaced by DenseMatrix.valueOf(Field[][])
static <F extends Field<F>> Matrix<F>	valueOf(Vector<F> diagonal, F zero) Deprecated. Since 3.3 - Replaced by SparseMatrix.valueOf(Vector, Field)
abstract Vector<F>	vectorization() Returns the vectorization of this matrix.

Methods inherited from class javolution.context.RealtimeObject

export, isLocal, move, moveHeap, preserve, toString, unpreserve

Methods inherited from class java.lang.Object

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

Methods inherited from interface javolution.context.Realtime

move

Field Detail

XML

protected static final XMLFormat<Matrix> XML

Holds the default XML representation for matrices. For example:

    <DenseMatrix rows="2" columns="2">
        <Complex real="1.0" imaginary="0.0" />
        <Complex real="0.0" imaginary="1.0" />
        <Complex real="0.0" imaginary="0.4" />
        <Complex real="-5.0" imaginary="-1.0" />
    </DenseMatrix>

Constructor Detail

Matrix

protected Matrix()

Default constructor (for sub-classes).

Method Detail

valueOf

public static <F extends Field<F>> Matrix<F> valueOf(F[][] elements)

Deprecated. Since 3.3 - Replaced by DenseMatrix.valueOf(Field[][])

Returns a dense matrix from the specified 2-dimensional array (convenience method).

Parameters:

elements - this matrix elements.

Returns:

the matrix having the specified elements.

Throws:

DimensionException - if rows have different length.

valueOf

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

Deprecated. Since 3.3 - Replaced by Float64Matrix.valueOf(double[][])

Returns a dense matrix from a 2-dimensional array of double values (convenience method).

Parameters:

values - the array of double values.

Returns:

the matrix having the specified elements.

Throws:

DimensionException - if rows have different length.

valueOf

public static Matrix<Complex> valueOf(Complex[][] elements)

Deprecated. Since 3.3 - Replaced by ComplexMatrix.valueOf(Complex[][])

Returns a dense matrix from a 2-dimensional array of complex numbers (convenience method).

Parameters:

elements - the array of complex elements.

Returns:

the matrix having the specified elements.

Throws:

DimensionException - if rows have different length.

valueOf

public static <F extends Field<F>> Matrix<F> valueOf(Vector<F> diagonal,
                                                     F zero)

Deprecated. Since 3.3 - Replaced by SparseMatrix.valueOf(Vector, Field)

Returns the sparse square matrix having the specified diagonal vector.

Parameters:

diagonal - the diagonal vector.

zero - value of non-diagonal elements.

Returns:

a square matrix with diagonal on the diagonal and zero elsewhere.

getNumberOfRows

public abstract int getNumberOfRows()

Returns the number of rows m for this matrix.

Returns:

m, the number of rows.

getNumberOfColumns

public abstract int getNumberOfColumns()

Returns the number of columns n for this matrix.

Returns:

n, the number of columns.

get

public abstract F 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))

getRow

public abstract Vector<F> getRow(int i)

Returns the row identified by the specified index in this matrix.

Parameters:

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

Returns:

the vector holding the specified row.

Throws:

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

getColumn

public abstract Vector<F> getColumn(int j)

Returns the column identified by the specified index in this matrix.

Parameters:

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

Returns:

the vector holding the specified column.

Throws:

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

getDiagonal

public abstract Vector<F> getDiagonal()

Returns the diagonal vector.

Returns:

the vector holding the diagonal elements.

opposite

public abstract Matrix<F> opposite()

Returns the negation of this matrix.

Specified by:

opposite in interface GroupAdditive<Matrix<F extends Field<F>>>

Returns:

-this.

plus

public abstract Matrix<F> plus(Matrix<F> that)

Returns the sum of this matrix with the one specified.

Specified by:

plus in interface GroupAdditive<Matrix<F extends Field<F>>>

Parameters:

that - the matrix to be added.

Returns:

this + that.

Throws:

DimensionException - matrices's dimensions are different.

minus

public Matrix<F> minus(Matrix<F> 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.

times

public abstract Matrix<F> times(F k)

Returns the product of this matrix by the specified factor.

Specified by:

times in interface VectorSpace<Matrix<F extends Field<F>>,F extends Field<F>>

Parameters:

k - the coefficient multiplier.

Returns:

this · k

times

public abstract Vector<F> times(Vector<F> v)

Returns the product of this matrix by the specified vector.

Parameters:

v - the vector.

Returns:

this · v

Throws:

DimensionException - if v.getDimension() != this.getNumberOfColumns()

times

public abstract Matrix<F> times(Matrix<F> that)

Returns the product of this matrix with the one specified.

Specified by:

times in interface Ring<Matrix<F extends Field<F>>>

Parameters:

that - the matrix multiplier.

Returns:

this · that.

Throws:

DimensionException - if this.getNumberOfColumns() != that.getNumberOfRows().

inverse

public abstract Matrix<F> inverse()

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

Returns:

1 / this

Throws:

DimensionException - if this matrix is not square.

divide

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

Returns this matrix divided by the one specified.

Parameters:

that - the matrix divisor.

Returns:

this / that.

Throws:

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

pseudoInverse

public Matrix<F> pseudoInverse()

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.

determinant

public abstract F determinant()

Returns the determinant of this matrix.

Returns:

this matrix determinant.

Throws:

DimensionException - if this matrix is not square.

transpose

public abstract Matrix<F> transpose()

Returns the transpose of this matrix.

Returns:

A'.

cofactor

public abstract F 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.

adjoint

public abstract Matrix<F> 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.

isSquare

public boolean isSquare()

Indicates if this matrix is square.

Returns:

getNumberOfRows() == getNumberOfColumns()

solve

public Vector<F> solve(Vector<F> y)

Solves this matrix for the specified vector (returns x such as this · x = y).

Parameters:

y - the vector for which the solution is calculated.

Returns:

x such as this · x = y

Throws:

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

solve

public Matrix<F> solve(Matrix<F> y)

Solves this matrix for the specified matrix (returns x such as this · x = y).

Parameters:

y - the matrix for which the solution is calculated.

Returns:

x such as this · x = y

Throws:

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

pow

public Matrix<F> 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.

trace

public F trace()

Returns the trace of this matrix.

Returns:

the sum of the diagonal elements.

tensor

public abstract Matrix<F> tensor(Matrix<F> that)

Returns the linear algebraic matrix tensor product of this matrix and another (Kronecker product). The default implementation returns a DenseMatrix.

Parameters:

that - the second matrix.

Returns:

this ⊗ that

See Also:

Wikipedia: Kronecker Product

vectorization

public abstract Vector<F> vectorization()

Returns the vectorization of this matrix. The vectorization of a matrix is the column vector obtain by stacking the columns of the matrix on top of one another. The default implementation returns a DenseVector.

Returns:

the vectorization of this matrix.

See Also:

Wikipedia: Vectorization.

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.

equals

public boolean equals(Matrix<F> that,
                      java.util.Comparator<F> cmp)

Indicates if this matrix can be considered equals to the one specified using the specified comparator when testing for element equality. The specified comparator may allow for some tolerance in the difference between the matrix elements.

Parameters:

that - the matrix to compare for equality.

cmp - the comparator to use when testing for element equality.

Returns:

true if this matrix and the specified matrix are both matrices with equal elements according to the specified comparator; false otherwise.

equals

public boolean equals(java.lang.Object that)

Indicates if this matrix is strictly 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 both matrices with equal elements; false otherwise.

See Also:

equals(Matrix, Comparator)

hashCode

public int hashCode()

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

Overrides:

hashCode in class java.lang.Object

Returns:

this matrix hash code value.

See Also:

equals(org.jscience.mathematics.vectors.Matrix, java.util.Comparator)