gov.sandia.cognition.math.matrix.custom

Class ParallelSparseMatrix

java.lang.Object

gov.sandia.cognition.util.AbstractCloneableSerializable

gov.sandia.cognition.math.AbstractRing<Matrix>

gov.sandia.cognition.math.matrix.AbstractMatrix

gov.sandia.cognition.math.matrix.custom.SparseMatrix

gov.sandia.cognition.math.matrix.custom.ParallelSparseMatrix

All Implemented Interfaces:

Matrix, Vectorizable, Ring<Matrix>, CloneableSerializable, java.io.Serializable, java.lang.Cloneable, java.lang.Iterable<MatrixEntry>

@PublicationReference(author="Wikipedia",
                      title="Sparse Matrix / Yale format",
                      type=WebPage,
                      year=2013,
                      url="http://en.wikipedia.org/wiki/Sparse_matrix#Yale_format")
public class ParallelSparseMatrix
extends SparseMatrix

A sparse matrix implementation. This stores the data in two formats: The first is as an array of sparse vectors for each row. This format is easy to modify (see the set* methods), but slow to operate on due to each element being dispersed to different locations in memory. The second is the compressed Yale format (see http://en.wikipedia.org/wiki/Sparse_matrix#Yale_format). This format densely packs the values into arrays of double -- permitting fast computation, but difficult and costly modification. This switches between the formats as necessary (to Yale when multiplying, to sparse vector when altering), so it is recommended that computation calls not be interleaved with modification calls unnecessarily. At present, this class extends SparseMatrix to leverage the serial implementations for all methods not-yet parallelized. The parallelized operations perform their work in parallel, but can't be called asynchronously. That is, the caller can't call "times(Vector)" and then do other work in parallel while waiting for the result. If you were to do so and called any methods that affected this matrix or the input vector, the results of the multiply could go very wrong.

Since:

3.4.3

Author:

Jeremy D. Wendt

See Also:

Serialized Form

Field Summary

Fields inherited from class gov.sandia.cognition.math.matrix.custom.SparseMatrix

columnIndices, firstIndicesForRows, values

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ParallelSparseMatrix() This should never be called by anything or anyone other than Java's serialization code.
	ParallelSparseMatrix(DenseMatrix d, int numThreads) Creates a new sparse matrix with the same dimensions and data as d (performs a deep copy).
	ParallelSparseMatrix(DiagonalMatrix d, int numThreads) Creates a new sparse matrix with the same dimensions and data as d (performs a deep copy).
	ParallelSparseMatrix(int numRows, int numCols, int numThreads) Creates a new parallel sparse matrix with the specified number of rows and columns.
	ParallelSparseMatrix(ParallelSparseMatrix m) Creates a new sparse matrix with the same dimensions and data as m (performs a deep copy).
	ParallelSparseMatrix(SparseMatrix m, int numThreads) Creates a new sparse matrix with the same dimensions and data as m (performs a deep copy).

Method Summary

Modifier and Type	Method and Description
protected void	checkSolveDimensions(Matrix b) Checks that the input matrix has the same numRows as this's numRows (otherwise, there can be no soluation for Ax = b).
protected void	checkSolveDimensions(Vector b) Checks that the input vector has the same dimensionality as this's numRows (otherwise, there can be no solution for Ax = b).
protected void	checkSubmatrixRange(int minRow, int maxRow, int minCol, int maxCol) Helper method checks that the input submatrix range is acceptable for this matrix, including that the max is greater than or equal to the min.
Matrix	clone() This makes public the clone method on the Object class and removes the exception that it throws.
Matrix	dotTimes(Matrix other) Element-wise multiplication of this and other
void	dotTimesEquals(Matrix other) Inline element-wise multiplication of this and other
Matrix	minus(Matrix other) Arithmetic subtraction of other from this
void	minusEquals(Matrix other) Inline arithmetic subtraction of other from this
Matrix	plus(Matrix other) Arithmetic addition of this and other
void	plusEquals(Matrix other) Inline arithmetic addition of this and other
Vector	preTimes(Vector vector) Package-private method that puts the vector * matrix code in the matrix class instead of in the vector class (why should vectors know the internals of matrices?).
void	scaledPlusEquals(double scaleFactor, Matrix other) Inline arithmetic addition of this and other after element-wise scaling of other by scaleFactor.
Vector	times(DenseVector vector) Type-specific version of times for combining whatever type this is with the input dense vector.
Matrix	times(Matrix other) Matrix multiplication of this and matrix, operates like the "*" operator in Matlab
Vector	times(SparseVector vector) Type-specific version of times for combining whatever type this is with the input sparse vector.
Vector	times(Vector vector) Returns the column vector from the equation return = this * vector
java.lang.String	toString(java.text.NumberFormat format) Converts the vector to a String, using the given formatter.

Methods inherited from class gov.sandia.cognition.math.matrix.custom.SparseMatrix

compress, convertFromVector, convertToVector, decompress, dotTimesEquals, dotTimesEquals, dotTimesEquals, get, getColumn, getElement, getEntryCount, getMatrixFactory, getNonZeroValueIterator, getNonZeroValueIterator, getNumColumns, getNumRows, getRow, getSubMatrix, identity, inverse, isCompressed, isSparse, isSquare, isSymmetric, isZero, isZero, iterator, logDeterminant, minusEquals, minusEquals, minusEquals, normFrobenius, normFrobeniusSquared, plusEquals, plusEquals, plusEquals, preTimes, preTimes, preTimes, pseudoInverse, rank, scaledPlusEquals, scaledPlusEquals, scaledPlusEquals, scaleEquals, set, setElement, solve, solve, sumOfColumns, sumOfRows, times, times, times, transpose

Methods inherited from class gov.sandia.cognition.math.matrix.AbstractMatrix

assertMultiplicationDimensions, assertSameDimensions, checkMultiplicationDimensions, checkSameDimensions, decrement, decrement, dotDivide, dotDivideEquals, equals, equals, getColumnInto, getRowInto, hashCode, increment, increment, isSymmetric, pseudoInverse, rank, setColumn, setRow, setSubMatrix, toArray, trace, valuesAsList

Methods inherited from class gov.sandia.cognition.math.AbstractRing

negative, negativeEquals, scale, scaledMinus, scaledMinusEquals, scaledPlus, zero

Methods inherited from class java.lang.Object

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

Methods inherited from interface gov.sandia.cognition.math.matrix.Matrix

toString

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Methods inherited from interface gov.sandia.cognition.math.Ring

negative, negativeEquals, scale, scaledMinus, scaledMinusEquals, scaledPlus, zero

Constructor Detail

ParallelSparseMatrix

public ParallelSparseMatrix(int numRows,
                            int numCols,
                            int numThreads)

Creates a new parallel sparse matrix with the specified number of rows and columns. All values are implicitly set to zero. NOTE: Upon completion this is in the sparse vector format.

Parameters:

numRows - The number of rows in the matrix

numCols - The number of columns in the matrix

numThreads - The number of threads to use for parallelized operations

ParallelSparseMatrix

public ParallelSparseMatrix(ParallelSparseMatrix m)

Creates a new sparse matrix with the same dimensions and data as m (performs a deep copy). NOTE: Upon completion this is in the same format as m.

Parameters:

m - The sparse matrix to copy

ParallelSparseMatrix

public ParallelSparseMatrix(SparseMatrix m,
                            int numThreads)

Creates a new sparse matrix with the same dimensions and data as m (performs a deep copy). NOTE: Upon completion this is in the same format as m.

Parameters:

m - The sparse matrix to copy

numThreads - The number of threads to use for parallelized operations

ParallelSparseMatrix

public ParallelSparseMatrix(DenseMatrix d,
                            int numThreads)

Creates a new sparse matrix with the same dimensions and data as d (performs a deep copy). NOTE: Upon completion this is in the compressed Yale format.

Parameters:

d - The dense matrix to copy

numThreads - The number of threads to use for parallelized operations

ParallelSparseMatrix

public ParallelSparseMatrix(DiagonalMatrix d,
                            int numThreads)

Creates a new sparse matrix with the same dimensions and data as d (performs a deep copy). NOTE: Upon completion this is in the compressed Yale format.

Parameters:

d - The diagonal matrix to copy

numThreads - The number of threads to use for parallelized operations

ParallelSparseMatrix

protected ParallelSparseMatrix()

This should never be called by anything or anyone other than Java's serialization code.

Method Detail

clone

public final Matrix clone()

This makes public the clone method on the Object class and removes the exception that it throws. Its default behavior is to automatically create a clone of the exact type of object that the clone is called on and to copy all primitives but to keep all references, which means it is a shallow copy. Extensions of this class may want to override this method (but call super.clone() to implement a "smart copy". That is, to target the most common use case for creating a copy of the object. Because of the default behavior being a shallow copy, extending classes only need to handle fields that need to have a deeper copy (or those that need to be reset). Some of the methods in ObjectUtil may be helpful in implementing a custom clone method. Note: The contract of this method is that you must use super.clone() as the basis for your implementation. NOTE: This does not affect this's format. The cloned matrix is in the same format as this. NOTE: This does not affect this's format. The cloned matrix is in the same format as this.

Specified by:

clone in interface Matrix

Specified by:

clone in interface Vectorizable

Specified by:

clone in interface Ring<Matrix>

Specified by:

clone in interface CloneableSerializable

Overrides:

clone in class SparseMatrix

Returns:

A clone of this object.

times

public Vector times(SparseVector vector)

Type-specific version of times for combining whatever type this is with the input sparse vector. NOTE: Upon completion this is in the compressed Yale format. NOTE: Upon completion this is in the compressed Yale format.

Overrides:

times in class SparseMatrix

Parameters:

vector - A sparse vector to multiply with this

Returns:

times

public Vector times(DenseVector vector)

Type-specific version of times for combining whatever type this is with the input dense vector. NOTE: Upon completion this is in the compressed Yale format. NOTE: Upon completion this is in the compressed Yale format.

Overrides:

times in class SparseMatrix

Parameters:

vector - A dense vector to multiply with this

Returns:

plus

public final Matrix plus(Matrix other)

Description copied from interface: Ring

Arithmetic addition of this and other

Specified by:

plus in interface Ring<Matrix>

Overrides:

plus in class AbstractRing<Matrix>

Parameters:

other - object to add to this

Returns:

sum of this and other

minus

public final Matrix minus(Matrix other)

Description copied from interface: Ring

Arithmetic subtraction of other from this

Specified by:

minus in interface Ring<Matrix>

Overrides:

minus in class AbstractRing<Matrix>

Parameters:

other - object to subtract from this

Returns:

difference of this and other

dotTimes

public final Matrix dotTimes(Matrix other)

Description copied from interface: Ring

Element-wise multiplication of this and other

Specified by:

dotTimes in interface Ring<Matrix>

Overrides:

dotTimes in class AbstractRing<Matrix>

Parameters:

other - elements of other will be multiplied to the corresponding elements of this

Returns:

element-wise multiplication of this and other

plusEquals

public final void plusEquals(Matrix other)

Description copied from interface: Ring

Inline arithmetic addition of this and other

Specified by:

plusEquals in interface Ring<Matrix>

Overrides:

plusEquals in class AbstractMatrix

Parameters:

other - object to add to this

scaledPlusEquals

public final void scaledPlusEquals(double scaleFactor,
                                   Matrix other)

Description copied from interface: Ring

Inline arithmetic addition of this and other after element-wise scaling of other by scaleFactor. If this is x, other is y, and scaleFactor is a, then this method is equivalent to x += a * y. It is typically a more efficient way of doing this.plusEquals(other.scale(scaleFactor)) since it can avoid intermediate object creation.

Specified by:

scaledPlusEquals in interface Ring<Matrix>

Overrides:

scaledPlusEquals in class AbstractMatrix

Parameters:

scaleFactor - The scale factor to multiply by the elements of other before adding to the elements of this.

other - Object to scale and then add to this.

minusEquals

public final void minusEquals(Matrix other)

Description copied from interface: Ring

Inline arithmetic subtraction of other from this

Specified by:

minusEquals in interface Ring<Matrix>

Overrides:

minusEquals in class AbstractMatrix

Parameters:

other - object to subtract from this

dotTimesEquals

public final void dotTimesEquals(Matrix other)

Description copied from interface: Ring

Inline element-wise multiplication of this and other

Specified by:

dotTimesEquals in interface Ring<Matrix>

Overrides:

dotTimesEquals in class AbstractMatrix

Parameters:

other - elements of other will be multiplied to the corresponding elements of this

times

public final Matrix times(Matrix other)

Description copied from interface: Matrix

Matrix multiplication of this and matrix, operates like the "*" operator in Matlab

Specified by:

times in interface Matrix

Overrides:

times in class AbstractMatrix

Parameters:

other - this.getNumColumns()==matrix.getNumRows()

Returns:

Matrix multiplication of this and matrix, will this.getNumRows() rows and matrix.getNumColumns() columns

times

public final Vector times(Vector vector)

Description copied from interface: Matrix

Returns the column vector from the equation return = this * vector

Specified by:

times in interface Matrix

Overrides:

times in class AbstractMatrix

Parameters:

vector - Vector by which to post-multiply this, must have the same number of rows as this

Returns:

Vector with the same dimensionality as the number of rows as this and vector

preTimes

public final Vector preTimes(Vector vector)

Package-private method that puts the vector * matrix code in the matrix class instead of in the vector class (why should vectors know the internals of matrices?).

Parameters:

vector - The vector to pre-multiply this by

Returns:

The resulting vector from input * this

Throws:

DimensionalityMismatchException - if the input vectors's dimensions doesn't match this's numRows.

checkSubmatrixRange

protected final void checkSubmatrixRange(int minRow,
                                         int maxRow,
                                         int minCol,
                                         int maxCol)

Helper method checks that the input submatrix range is acceptable for this matrix, including that the max is greater than or equal to the min. Note that the input mins and maxs are inclusive.

Parameters:

minRow - The minimum row to return (inclusive)

maxRow - The maximum row to return (inclusive)

minCol - The minimum column to return (inclusive)

maxCol - The maximum column to return (inclusive)

Throws:

java.lang.ArrayIndexOutOfBoundsException - if the input range is illegal or outside the bounds of this.

checkSolveDimensions

protected final void checkSolveDimensions(Vector b)

Checks that the input vector has the same dimensionality as this's numRows (otherwise, there can be no solution for Ax = b).

Parameters:

b - The RHS vector

Throws:

java.lang.IllegalArgumentException - if the input's size doesn't match this's numRows

checkSolveDimensions

protected final void checkSolveDimensions(Matrix b)

Checks that the input matrix has the same numRows as this's numRows (otherwise, there can be no soluation for Ax = b).

Parameters:

b - The RHS matrix

Throws:

java.lang.IllegalArgumentException - if the input's size doesn't match this's numRows

toString

public final java.lang.String toString(java.text.NumberFormat format)

Description copied from interface: Matrix

Converts the vector to a String, using the given formatter.

Parameters:

format - The number format to use.

Returns:

The String representation of the Matrix.