org.jscience.mathematics.vector

Class SparseMatrix<F extends Field<F>>

java.lang.Object

org.jscience.mathematics.vector.Matrix<F>

org.jscience.mathematics.vector.SparseMatrix<F>

All Implemented Interfaces:

javolution.lang.Immutable, javolution.lang.Realtime, javolution.lang.ValueType, GroupAdditive<Matrix<F>>, Ring<Matrix<F>>, Structure<Matrix<F>>, VectorSpace<Matrix<F>,F>

public final class SparseMatrix<F extends Field<F>>
extends Matrix<F>

This class represents a matrix made of sparse vectors (as rows). To create a sparse matrix made of column vectors the transpose() method can be used. For example:[code] SparseVector column0 = SparseVector.valueOf(...); SparseVector column1 = SparseVector.valueOf(...); SparseMatrix M = SparseMatrix.valueOf(column0, column1).transpose(); [/code]

As for any concrete structure, this class is declared final (otherwise most operations would have to be overridden to return the appropriate type). Specialized dense matrix should sub-class Matrix directly. For example:[code] // Extension through composition. final class BandMatrix > extends Matrix { private SparseMatrix _value; ... public BandMatrix opposite() { // Returns the right type. return BandMatrix.valueOf(_value.opposite()); } ... }[/code]

Version:

3.3, January 2, 2007

Author:

Jean-Marie Dautelle

Method Summary

Modifier and Type	Method and Description
SparseMatrix<F>	adjoint() Returns the adjoint of this matrix.
F	cofactor(int i, int j) Returns the cofactor of an element in this matrix.
SparseMatrix<F>	copy() Returns a copy of this matrix allocated by the calling thread (possibly on the stack).
F	determinant() Returns the determinant of this matrix.
F	get(int i, int j) Returns a single element from this matrix.
SparseVector<F>	getColumn(int j) Returns the column identified by the specified index in this matrix.
SparseVector<F>	getDiagonal() Returns the diagonal vector.
int	getNumberOfColumns() Returns the number of columns n for this matrix.
int	getNumberOfRows() Returns the number of rows m for this matrix.
SparseVector<F>	getRow(int i) Returns the row identified by the specified index in this matrix.
F	getZero() Returns the value of the non-set elements for this sparse matrix.
SparseMatrix<F>	inverse() Returns the inverse of this matrix (must be square).
SparseMatrix<F>	minus(Matrix<F> that) Returns the difference between this matrix and the one specified.
SparseMatrix<F>	opposite() Returns the negation of this matrix.
SparseMatrix<F>	plus(Matrix<F> that) Returns the sum of this matrix with the one specified.
Matrix<F>	solve(Matrix<F> y) Solves this matrix for the specified matrix (returns x such as this · x = y).
SparseMatrix<F>	tensor(Matrix<F> that) Returns the linear algebraic matrix tensor product of this matrix and another (Kronecker product).
SparseMatrix<F>	times(F k) Returns the product of this matrix by the specified factor.
SparseMatrix<F>	times(Matrix<F> that) Returns the product of this matrix with the one specified.
SparseVector<F>	times(Vector<F> v) Returns the product of this matrix by the specified vector.
SparseMatrix<F>	transpose() Returns the transpose of this matrix.
static <F extends Field<F>> SparseMatrix<F>	valueOf(java.util.List<SparseVector<F>> rows) Returns a sparse matrix holding the row vectors from the specified collection (column vectors if transposed).
static <F extends Field<F>> SparseMatrix<F>	valueOf(Matrix<F> that, F zero) Returns a sparse matrix equivalent to the specified matrix but with the zero elements removed using the default object equality comparator.
static <F extends Field<F>> SparseMatrix<F>	valueOf(Matrix<F> that, F zero, <any> comparator) Returns a sparse matrix equivalent to the specified matrix but with the zero elements removed using the specified object equality comparator.
static <F extends Field<F>> SparseMatrix<F>	valueOf(SparseVector<F>... rows) Returns a sparse matrix holding the specified row vectors (column vectors if transposed).
static <F extends Field<F>> SparseMatrix<F>	valueOf(Vector<F> diagonal, F zero) Returns the sparse square matrix having the specified diagonal vector.
SparseVector<F>	vectorization() Returns the vectorization of this matrix.

Methods inherited from class org.jscience.mathematics.vector.Matrix

divide, equals, equals, hashCode, isSquare, pow, pseudoInverse, solve, toString, toText, trace

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Method Detail

valueOf

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

Returns the sparse square matrix having the specified diagonal vector. This method is typically used to create an identity matrix. For example:[code] SparseMatrix IDENTITY = Matrix.valueOf( DenseVector.valueOf({Real.ONE, Real.ONE, Real.ONE}), Real.ZERO); [/code]

Parameters:

diagonal - the diagonal vector.

zero - value of non-diagonal elements.

Returns:

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

valueOf

public static <F extends Field<F>> SparseMatrix<F> valueOf(SparseVector<F>... rows)

Returns a sparse matrix holding the specified row vectors (column vectors if transposed).

Parameters:

rows - the row vectors.

Returns:

the matrix having the specified rows.

Throws:

DimensionException - if the rows do not have the same dimension.

valueOf

public static <F extends Field<F>> SparseMatrix<F> valueOf(java.util.List<SparseVector<F>> rows)

Returns a sparse matrix holding the row vectors from the specified collection (column vectors if transposed).

Parameters:

rows - the list of row vectors.

Returns:

the matrix having the specified rows.

Throws:

DimensionException - if the rows do not have the same dimension.

valueOf

public static <F extends Field<F>> SparseMatrix<F> valueOf(Matrix<F> that,
                                                           F zero)

Returns a sparse matrix equivalent to the specified matrix but with the zero elements removed using the default object equality comparator.

Parameters:

that - the matrix to convert.

zero - the zero element for the sparse vector to return.

Returns:

SparseMatrix.valueOf(that, zero, FastComparator.DEFAULT) or a dense matrix holding the same elements

valueOf

public static <F extends Field<F>> SparseMatrix<F> valueOf(Matrix<F> that,
                                                           F zero,
                                                           <any> comparator)

Returns a sparse matrix equivalent to the specified matrix but with the zero elements removed using the specified object equality comparator.

Parameters:

that - the matrix to convert.

zero - the zero element for the sparse vector to return.

comparator - the comparator used to determinate zero equality.

Returns:

that or a dense matrix holding the same elements as the specified matrix.

getZero

public F getZero()

Returns the value of the non-set elements for this sparse matrix.

Returns:

the element corresponding to zero.

getNumberOfRows

public int getNumberOfRows()

Description copied from class: Matrix

Returns the number of rows m for this matrix.

Specified by:

getNumberOfRows in class Matrix<F extends Field<F>>

Returns:

m, the number of rows.

getNumberOfColumns

public int getNumberOfColumns()

Description copied from class: Matrix

Returns the number of columns n for this matrix.

Specified by:

getNumberOfColumns in class Matrix<F extends Field<F>>

Returns:

n, the number of columns.

get

public F get(int i,
             int j)

Description copied from class: Matrix

Returns a single element from this matrix.

Specified by:

get in class Matrix<F extends Field<F>>

Parameters:

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

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

Returns:

the element read at [i,j].

getRow

public SparseVector<F> getRow(int i)

Description copied from class: Matrix

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

Specified by:

getRow in class Matrix<F extends Field<F>>

Parameters:

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

Returns:

the vector holding the specified row.

getColumn

public SparseVector<F> getColumn(int j)

Description copied from class: Matrix

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

Specified by:

getColumn in class Matrix<F extends Field<F>>

Parameters:

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

Returns:

the vector holding the specified column.

getDiagonal

public SparseVector<F> getDiagonal()

Description copied from class: Matrix

Returns the diagonal vector.

Specified by:

getDiagonal in class Matrix<F extends Field<F>>

Returns:

the vector holding the diagonal elements.

opposite

public SparseMatrix<F> opposite()

Description copied from class: Matrix

Returns the negation of this matrix.

Specified by:

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

Specified by:

opposite in class Matrix<F extends Field<F>>

Returns:

-this.

plus

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

Description copied from class: Matrix

Returns the sum of this matrix with the one specified.

Specified by:

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

Specified by:

plus in class Matrix<F extends Field<F>>

Parameters:

that - the matrix to be added.

Returns:

this + that.

minus

public SparseMatrix<F> minus(Matrix<F> that)

Description copied from class: Matrix

Returns the difference between this matrix and the one specified.

Overrides:

minus in class Matrix<F extends Field<F>>

Parameters:

that - the matrix to be subtracted.

Returns:

this - that.

times

public SparseMatrix<F> times(F k)

Description copied from class: Matrix

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>>

Specified by:

times in class Matrix<F extends Field<F>>

Parameters:

k - the coefficient multiplier.

Returns:

this · k

times

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

Description copied from class: Matrix

Returns the product of this matrix by the specified vector.

Specified by:

times in class Matrix<F extends Field<F>>

Parameters:

v - the vector.

Returns:

this · v

times

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

Description copied from class: Matrix

Returns the product of this matrix with the one specified.

Specified by:

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

Specified by:

times in class Matrix<F extends Field<F>>

Parameters:

that - the matrix multiplier.

Returns:

this · that.

inverse

public SparseMatrix<F> inverse()

Description copied from class: Matrix

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

Specified by:

inverse in class Matrix<F extends Field<F>>

Returns:

1 / this

determinant

public F determinant()

Description copied from class: Matrix

Returns the determinant of this matrix.

Specified by:

determinant in class Matrix<F extends Field<F>>

Returns:

this matrix determinant.

solve

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

Description copied from class: Matrix

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

Overrides:

solve in class Matrix<F extends Field<F>>

Parameters:

y - the matrix for which the solution is calculated.

Returns:

x such as this · x = y

transpose

public SparseMatrix<F> transpose()

Description copied from class: Matrix

Returns the transpose of this matrix.

Specified by:

transpose in class Matrix<F extends Field<F>>

Returns:

A'.

cofactor

public F cofactor(int i,
                  int j)

Description copied from class: Matrix

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.

Specified by:

cofactor in class Matrix<F extends Field<F>>

Parameters:

i - the row index.

j - the column index.

Returns:

the cofactor of THIS[i,j].

adjoint

public SparseMatrix<F> adjoint()

Description copied from class: Matrix

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.

Specified by:

adjoint in class Matrix<F extends Field<F>>

Returns:

the adjoint of this matrix.

tensor

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

Description copied from class: Matrix

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

Specified by:

tensor in class Matrix<F extends Field<F>>

Parameters:

that - the second matrix.

Returns:

this ⊗ that

See Also:

Wikipedia: Kronecker Product

vectorization

public SparseVector<F> vectorization()

Description copied from class: Matrix

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.

Specified by:

vectorization in class Matrix<F extends Field<F>>

Returns:

the vectorization of this matrix.

See Also:

Wikipedia: Vectorization.

copy

public SparseMatrix<F> copy()

Description copied from class: Matrix

Returns a copy of this matrix allocated by the calling thread (possibly on the stack).

Specified by:

copy in interface javolution.lang.ValueType

Specified by:

copy in class Matrix<F extends Field<F>>

Returns:

an identical and independant copy of this matrix.