com.numericalmethod.suanshu.matrix.doubles.matrixtype.sparse
Class DokSparseMatrix

java.lang.Object
  com.numericalmethod.suanshu.matrix.doubles.matrixtype.sparse.DokSparseMatrix

All Implemented Interfaces:

DeepCopyable, AbelianGroup<Matrix>, Monoid<Matrix>, Ring<Matrix>, Matrix, MatrixAccessor, MatrixRing, Densifiable, SparseMatrix, SparseStructure, MatrixDimension

public class DokSparseMatrix
extends java.lang.Object

The dictionary of key (DOK) format for sparse matrix. Using the coordinates of non-zero entries in the matrix as the keys, the non-zero values are hashed such that adding, removing, retrieving values can be done in constant time.

This data structure is efficient for incremental construction but poor for iterating non-zero elements in a matrix.

Field Summary

protected int	nCols
protected int	nRows

Constructor Summary

DokSparseMatrix(DokSparseMatrix that)
Copy constructor.

DokSparseMatrix(int nRows, int nCols)
Create an instance of DOK sparse matrix with the matrix dimension.

DokSparseMatrix(int nRows, int nCols, int[] rowIndices, int[] columnIndices, double[] values)
Create an instance of DOK sparse matrix with non-zero values.

DokSparseMatrix(int nRows, int nCols, java.util.List<SparseElement> elementList)
Create an instance of DOK sparse matrix with a list of non-zero SparseElements.

Method Summary

Matrix	add(Matrix that) this + that
DokSparseMatrix	deepCopy() The implementation can return an instance created from this by the copy constructor of the class, or just this if the instance itself is immutable.
int	dropTolerance(double tolerance) Remove non-zero entries x whose magnitude is less than or equal to the tolerance, i.e., (|x| <= tolerance).
boolean	equals(java.lang.Object obj)
double	get(int row, int col) Get the matrix entry at [row, col].
Vector	getColumn(int col) Get a specified column as a vector.
Vector	getRow(int row) Get a specified row as a vector.
int	hashCode()
Matrix	minus(Matrix that) this - that
Matrix	multiply(Matrix that) this %*% that
Vector	multiply(Vector v) Right multiply this matrix, A by a vector.
int	nCols() Get the number of columns.
int	nnz() Get the number of non-zero entries in the matrix.
int	nRows() Get the number of rows.
Matrix	ONE() Get an identity matrix that has the same dimension as this matrix.
Matrix	opposite() Get the opposite of this matrix.
Matrix	scaled(double scalar) scalar * this
void	set(int row, int col, double value) Set the matrix entry at [row, col] to value.
Matrix	t() t(this) Compute the transpose of this matrix.
DenseMatrix	toDense() Densify a matrix, i.e., convert a matrix implementation to a standard dense matrix, DenseMatrix.
java.util.List<SparseElement>	toElementList() Export the non-zero values in the matrix as a list of SparseElements.
java.lang.String	toString()
Matrix	ZERO() The additive element 0 in the group, such that for all elements a in the group, the equation 0 + a = a + 0 = a holds.

Methods inherited from class java.lang.Object

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

Field Detail

nRows

protected final int nRows

nCols

protected final int nCols

Constructor Detail

DokSparseMatrix

public DokSparseMatrix(int nRows,
                       int nCols)

Create an instance of DOK sparse matrix with the matrix dimension.

Parameters:

nRows - the number of rows of the matrix

nCols - the number of columns of the matrix

DokSparseMatrix

public DokSparseMatrix(int nRows,
                       int nCols,
                       int[] rowIndices,
                       int[] columnIndices,
                       double[] values)

Create an instance of DOK sparse matrix with non-zero values.

Parameters:

nRows - the number of rows of the matrix

nCols - the number of columns of the matrix

rowIndices - the row indices of the input non-zeros

columnIndices - the column indices of the input non-zeros

values - the non-zero values

DokSparseMatrix

public DokSparseMatrix(int nRows,
                       int nCols,
                       java.util.List<SparseElement> elementList)

Create an instance of DOK sparse matrix with a list of non-zero SparseElements.

Parameters:

nRows - the number of rows of the matrix

nCols - the number of columns of the matrix

elementList - the element list

DokSparseMatrix

public DokSparseMatrix(DokSparseMatrix that)

Copy constructor.

Parameters:

that - the matrix to be copied

Method Detail

toElementList

public java.util.List<SparseElement> toElementList()

Description copied from interface: SparseMatrix

Export the non-zero values in the matrix as a list of SparseElements.

This is useful for converting between SparseMatrix of different formats. For example,

 // construct matrix using DOK
 DokSparseMatrix dok = new DokSparseMatrix(5, 5);
 // ... insert some values to DOK matrix
 // convert to CSR matrix for efficient matrix operations
 CsrSparseMatrix csr = new CsrSparseMatrix(5, 5, dok.toElementList());
 

Returns:

the element list

set

public void set(int row,
                int col,
                double value)

Description copied from interface: MatrixAccessor

Set the matrix entry at [row, col] to value.

This is the only method that may change the entries of a matrix.

Parameters:

row - the row index

col - the column index

value - the value to set A[row, col] to

get

public double get(int row,
                  int col)

Description copied from interface: MatrixAccessor

Get the matrix entry at [row, col].

Parameters:

row - the row index

col - the column index

Returns:

A[row, col]

getRow

public Vector getRow(int row)
              throws MatrixAccessException

Description copied from interface: MatrixAccessor

Get a specified row as a vector.

Parameters:

row - the row index

Returns:

a vector A[row, ]

Throws:

MatrixAccessException - when row < 1, or when row > number of rows

getColumn

public Vector getColumn(int col)
                 throws MatrixAccessException

Description copied from interface: MatrixAccessor

Get a specified column as a vector.

Parameters:

col - the column index

Returns:

a vector A[, col]

Throws:

MatrixAccessException - when col < 1, or when col > number of columns

add

public Matrix add(Matrix that)

Description copied from interface: MatrixRing

this + that

Specified by:

add in interface AbelianGroup<Matrix>

Specified by:

add in interface MatrixRing

Parameters:

that - another matrix

Returns:

the sum of this and that

minus

public Matrix minus(Matrix that)

Description copied from interface: MatrixRing

this - that

Specified by:

minus in interface AbelianGroup<Matrix>

Specified by:

minus in interface MatrixRing

Parameters:

that - another matrix

Returns:

the difference between this and that

multiply

public Matrix multiply(Matrix that)

Description copied from interface: MatrixRing

this %*% that

Specified by:

multiply in interface Monoid<Matrix>

Specified by:

multiply in interface MatrixRing

Parameters:

that - another matrix

Returns:

the product of this and that

multiply

public Vector multiply(Vector v)

Description copied from interface: Matrix

Right multiply this matrix, A by a vector.

Specified by:

multiply in interface Matrix

Parameters:

v - a vector

Returns:

A %*% v

scaled

public Matrix scaled(double scalar)

Description copied from interface: Matrix

scalar * this

Specified by:

scaled in interface Matrix

Parameters:

scalar - a double

Returns:

scalar * this

t

public Matrix t()

Description copied from interface: MatrixRing

t(this)

Compute the transpose of this matrix. The original matrix does not change. The returned value is independent and can be modified anyhow.

This is the involution on the matrix ring.

Specified by:

t in interface MatrixRing

Returns:

the transpose of this matrix, of the same type

ZERO

public Matrix ZERO()

Description copied from interface: AbelianGroup

The additive element 0 in the group, such that for all elements a in the group, the equation

0 + a = a + 0 = a

holds.

Returns:

0

ONE

public Matrix ONE()

Description copied from interface: MatrixRing

Get an identity matrix that has the same dimension as this matrix.

For a non-square matrix, it zeros out the rows (columns) with index > nCols (nRows).

Returns:

an identity matrix

deepCopy

public DokSparseMatrix deepCopy()

Description copied from interface: DeepCopyable

The implementation can return an instance created from this by the copy constructor of the class, or just this if the instance itself is immutable.

Returns:

an independent (deep) copy of the instance

toDense

public DenseMatrix toDense()

Description copied from interface: Densifiable

Densify a matrix, i.e., convert a matrix implementation to a standard dense matrix, DenseMatrix.

This is equivalent to

new DenseMatrix(Matrix A)

Individual matrix implementation may optimize the conversion by taking advantage of having access to the class' private members. In other words, toDense() is in general more efficient than explicit copy construction.

As an example, for some long matrix computations, we may not be sure about the return type. We can always cast it to the standard matrix. That is,

DenseMatrix A = B.multiply(C).add(D).minus(E).toDense();

This statement always works regardless of the types of B, C, D, and E.

Returns:

a matrix representation in DenseMatrix

nnz

public int nnz()

Description copied from interface: SparseStructure

Get the number of non-zero entries in the matrix.

Returns:

the number of non-zero entries in the matrix

dropTolerance

public int dropTolerance(double tolerance)

Description copied from interface: SparseStructure

Remove non-zero entries x whose magnitude is less than or equal to the tolerance, i.e., (|x| <= tolerance).

Parameters:

tolerance - the tolerance for non-zeros

Returns:

the number of non-zeros removed

nRows

public int nRows()

Description copied from interface: MatrixDimension

Get the number of rows. Rows count from 1.

Specified by:

nRows in interface MatrixDimension

Returns:

the number of rows

nCols

public int nCols()

Description copied from interface: MatrixDimension

Get the number of columns. Columns count from 1.

Specified by:

nCols in interface MatrixDimension

Returns:

the number of columns

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object

opposite

public Matrix opposite()

Description copied from interface: MatrixRing

Get the opposite of this matrix.

Specified by:

opposite in interface AbelianGroup<Matrix>

Specified by:

opposite in interface MatrixRing

Returns:

-this

See Also:

Wikipedia: Additive inverse

equals

public boolean equals(java.lang.Object obj)

Overrides:

equals in class java.lang.Object

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object