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

protected int[] 
columnIndices
Part of the compressed Yale format.

protected int[] 
firstIndicesForRows
Part of the compressed Yale format.

protected double[] 
values
Part of the compressed Yale format.

Modifier  Constructor and Description 

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


SparseMatrix(DenseMatrix d)
Creates a new sparse matrix with the same dimensions and data as d
(performs a deep copy).


SparseMatrix(DiagonalMatrix d)
Creates a new sparse matrix with the same dimensions and data as d
(performs a deep copy).


SparseMatrix(int numRows,
int numCols)
Creates a new sparse matrix with the specified number of rows and
columns.


SparseMatrix(SparseMatrix m)
Creates a new sparse matrix with the same dimensions and data as m
(performs a deep copy).

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. 
void 
compress()
This method is provided so that the calling programmer can explicitly
declare when a matrix should be compressed to the compressed Yale format.

void 
convertFromVector(Vector parameters)
uploads a matrix from a columnstacked vector of parameters, so that
v(k) = A(i,j) = A( k%M, k/M )

Vector 
convertToVector()
Creates a columnstacked version of this, so that
v(k) = A(i,j) = v(j*M+i)

void 
decompress()
This method is provided so that the calling programmer can explicitly
declare when a matrix should be decompressed from the compressed Yale
format.

Matrix 
dotTimes(Matrix other)
Elementwise multiplication of
this and other 
void 
dotTimesEquals(DenseMatrix other)
Typespecific version of dotTimesEquals for combining whatever type this
is with the input dense matrix.

void 
dotTimesEquals(DiagonalMatrix other)
Typespecific version of dotTimesEquals for combining whatever type this
is with the input diagonal matrix.

void 
dotTimesEquals(Matrix other)
Inline elementwise multiplication of
this and
other 
void 
dotTimesEquals(SparseMatrix other)
Typespecific version of dotTimesEquals for combining whatever type this
is with the input sparse matrix.

double 
get(int rowIndex,
int columnIndex)
Gets the value of the element of the matrix at the zerobased row and
column indices.

Vector 
getColumn(int columnIndex)
Gets the specified column from the zerobased index and returns a
vector that corresponds to that column.

double 
getElement(int rowIndex,
int columnIndex)
Gets the Matrix element at the specified zerobased indices
throws ArrayIndexOutOfBoundsException if either rowIndex or columnIndex
are less than 0, or greater than the number of rows (columns) minus one
(0 <= index <= num1)

int 
getEntryCount()
Gets the number of active entries in the matrix.

MatrixFactory<?> 
getMatrixFactory()
Gets a matrix factory, typically one associated with this type of matrix.

java.util.Iterator<MatrixEntry> 
getNonZeroValueIterator()
Deprecated.

java.util.Iterator<MatrixEntry> 
getNonZeroValueIterator(int startRow)
Returns an iterator over the nonzero entries in this matrix starting
with startRow.

int 
getNumColumns()
Returns the number of columns in the Matrix

int 
getNumRows()
Returns the number of rows in the Matrix

Vector 
getRow(int rowIndex)
Gets the specified row from the zerobased index and returns a vector
that corresponds to that column

Matrix 
getSubMatrix(int minRow,
int maxRow,
int minColumn,
int maxColumn)
Gets the embedded submatrix inside of the Matrix, specified by the
inclusive, zerobased indices such that the result matrix will have size
(maxRowminRow+1) x (maxColumminCcolumn+1)

void 
identity()
Formats the matrix as an identity matrix.

Matrix 
inverse()
Computes the fullblown inverse of
this , which must be a
square matrix 
boolean 
isCompressed()
This method tests if the matrix is currently compressed to the compressed
Yale format.

boolean 
isSparse()
Returns true if this matrix has a potentially sparse underlying
structure.

boolean 
isSquare()
Determines if the matrix is square (numRows == numColumns)

boolean 
isSymmetric(double effectiveZero)
Determines if the matrix is effectively symmetric

boolean 
isZero()
Determines if this ring is equal to zero.

boolean 
isZero(double effectiveZero)
Determines if this ring is equal to zero using the elementwise effective
zero value.

java.util.Iterator<MatrixEntry> 
iterator() 
ComplexNumber 
logDeterminant()
Computes the natural logarithm of the determinant of
this . 
Matrix 
minus(Matrix other)
Arithmetic subtraction of
other from this 
void 
minusEquals(DenseMatrix other)
Typespecific version of minusEquals for combining whatever type this is
with the input dense matrix.

void 
minusEquals(DiagonalMatrix other)
Typespecific version of minusEquals for combining whatever type this is
with the input diagonal matrix.

void 
minusEquals(Matrix other)
Inline arithmetic subtraction of
other from
this 
void 
minusEquals(SparseMatrix other)
Typespecific version of minusEquals for combining whatever type this is
with the input sparse matrix.

double 
normFrobenius()
Compute the Frobenius norm of
this , which is just a fancy
way of saying that I will square each element, add those up, and square
root the result. 
double 
normFrobeniusSquared()
Compute the squared Frobenius norm of
this , which is just a
fancy way of saying that I will square each element and add those up. 
Matrix 
plus(Matrix other)
Arithmetic addition of
this and other 
void 
plusEquals(DenseMatrix other)
Typespecific version of plusEquals for combining whatever type this is
with the input dense matrix.

void 
plusEquals(DiagonalMatrix other)
Typespecific version of plusEquals for combining whatever type this is
with the input diagonal matrix.

void 
plusEquals(Matrix other)
Inline arithmetic addition of
this and other 
void 
plusEquals(SparseMatrix other)
Typespecific version of plusEquals for combining whatever type this is
with the input sparse matrix.

Vector 
preTimes(DenseVector vector)
Typespecific version of pretimes for combining whatever type this is
with the input dense vector.

Matrix 
preTimes(DiagonalMatrix other)
Packageprivate helper for the diagonal matrix class.

Vector 
preTimes(SparseVector vector)
Typespecific version of pretimes for combining whatever type this is
with the input sparse vector.

Vector 
preTimes(Vector vector)
Packageprivate 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?).

Matrix 
pseudoInverse(double effectiveZero)
Computes the effective pseudoinverse of
this , using a
rather expensive procedure (SVD) 
int 
rank(double effectiveZero)
Computes the effective rank of
this , which is the number of
linearly independent rows and columns in this . 
void 
scaledPlusEquals(DenseMatrix other,
double scaleFactor)
Typespecific version of scaledPlusEquals for combining whatever type
this is with the input dense matrix.

void 
scaledPlusEquals(DiagonalMatrix other,
double scaleFactor)
Typespecific version of scaledPlusEquals for combining whatever type
this is with the input diagonal matrix.

void 
scaledPlusEquals(double scaleFactor,
Matrix other)
Inline arithmetic addition of
this and other after
elementwise scaling of other by scaleFactor . 
void 
scaledPlusEquals(SparseMatrix other,
double scaleFactor)
Typespecific version of scaledPlusEquals for combining whatever type
this is with the input sparse matrix.

void 
scaleEquals(double scaleFactor)
Inline elementwise scaling of
this by
scaleFactor 
void 
set(int rowIndex,
int columnIndex,
double value)
Sets the value of the element of the matrix at the zerobased row and
column indices.

void 
setElement(int rowIndex,
int columnIndex,
double value)
Sets the Matrix element at the specified zerobased indices
throws ArrayIndexOutOfBoundsException if either rowIndex or columnIndex
are less than 0, or greater than the number of rows (columns) minus one
(0 <= index <= num1)

Matrix 
solve(Matrix B)
Solves for "X" in the equation: this*X = B

Vector 
solve(Vector b)
Solves for "x" in the equation: this*x = b

Vector 
sumOfColumns()
Returns a new vector containing the sum across the columns.

Vector 
sumOfRows()
Returns a new vector containing the sum across the rows.

Matrix 
times(DenseMatrix other)
Typespecific version of times for combining whatever type this is with
the input dense matrix.

Vector 
times(DenseVector vector)
Typespecific version of times for combining whatever type this is with
the input dense vector.

Matrix 
times(DiagonalMatrix other)
Typespecific version of times for combining whatever type this is with
the input diagonal matrix.

Matrix 
times(Matrix other)
Matrix multiplication of
this and matrix ,
operates like the "* " operator in Matlab 
Matrix 
times(SparseMatrix other)
Typespecific version of times for combining whatever type this is with
the input sparse matrix.

Vector 
times(SparseVector vector)
Typespecific 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. 
Matrix 
transpose()
Returns the transpose of
this 
assertMultiplicationDimensions, assertSameDimensions, checkMultiplicationDimensions, checkSameDimensions, decrement, decrement, dotDivide, dotDivideEquals, equals, equals, getColumnInto, getRowInto, hashCode, increment, increment, isSymmetric, pseudoInverse, rank, setColumn, setRow, setSubMatrix, toArray, trace, valuesAsList
negative, negativeEquals, scale, scaledMinus, scaledMinusEquals, scaledPlus, zero
finalize, getClass, notify, notifyAll, toString, wait, wait, wait
negative, negativeEquals, scale, scaledMinus, scaledMinusEquals, scaledPlus, zero
protected double[] values
protected int[] firstIndicesForRows
protected int[] columnIndices
public SparseMatrix(int numRows, int numCols)
numRows
 The number of rows in the matrixnumCols
 The number of columns in the matrixpublic SparseMatrix(SparseMatrix m)
m
 The sparse matrix to copypublic SparseMatrix(DenseMatrix d)
d
 The dense matrix to copypublic SparseMatrix(DiagonalMatrix d)
d
 The diagonal matrix to copyprotected SparseMatrix()
public final void compress()
public final void decompress()
public final boolean isCompressed()
public Matrix clone()
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.clone
in interface Matrix
clone
in interface Vectorizable
clone
in interface Ring<Matrix>
clone
in interface CloneableSerializable
clone
in class AbstractRing<Matrix>
public boolean isSparse()
public int getEntryCount()
Matrix
public void scaledPlusEquals(SparseMatrix other, double scaleFactor)
other
 A sparse matrix to add to thisscaleFactor
 The amount to scale other bypublic void scaledPlusEquals(DenseMatrix other, double scaleFactor)
other
 A dense matrix to add to thisscaleFactor
 The amount to scale other bypublic void scaledPlusEquals(DiagonalMatrix other, double scaleFactor)
other
 A diagonal matrix to add to thisscaleFactor
 The amount to scale other bypublic final void plusEquals(SparseMatrix other)
other
 A sparse matrix to add to thispublic final void plusEquals(DenseMatrix other)
other
 A dense matrix to add to thispublic final void plusEquals(DiagonalMatrix other)
other
 A diagonal matrix to add to thispublic final void minusEquals(SparseMatrix other)
other
 A sparse matrix to subtract from thispublic final void minusEquals(DenseMatrix other)
other
 A dense matrix to subtract from thispublic final void minusEquals(DiagonalMatrix other)
other
 A diagonal matrix to subtract from thispublic final void dotTimesEquals(SparseMatrix other)
other
 A sparse matrix to dot with thispublic final void dotTimesEquals(DenseMatrix other)
other
 A dense matrix to dot with thispublic final void dotTimesEquals(DiagonalMatrix other)
other
 A diagonal matrix to dot with thispublic final Matrix times(SparseMatrix other)
other
 A sparse matrix to multiply with thispublic final Matrix times(DenseMatrix other)
other
 A dense matrix to multiply with thispublic final Matrix times(DiagonalMatrix other)
other
 A diagonal matrix to multiply with thispublic final Matrix preTimes(DiagonalMatrix other)
other
 The matrix to premultiply this bypublic Vector times(SparseVector vector)
vector
 A sparse vector to multiply with thispublic Vector times(DenseVector vector)
vector
 A dense vector to multiply with thispublic final void scaleEquals(double scaleFactor)
this
by
scaleFactor
NOTE: Upon completion this is in the compressed Yale format.scaleFactor
 amount to scale the elements of this
public final int getNumRows()
public final int getNumColumns()
public double get(int rowIndex, int columnIndex)
getElement
.
No change to compressed Yale or sparse row format.rowIndex
 The zerobased row index. Must be between 0 (inclusive) and the
number of rows (exclusive).columnIndex
 The zerobased column index. Must be between 0 (inclusive) and the
number of columns (exclusive).public final double getElement(int rowIndex, int columnIndex)
rowIndex
 Zerobased index into the MatrixcolumnIndex
 Zerobased index into the Matrixpublic void set(int rowIndex, int columnIndex, double value)
setElement
.
NOTE: Upon completion this is in the compressed Yale format.rowIndex
 The zerobased row index. Must be between 0 (inclusive) and the
number of rows (exclusive).columnIndex
 The zerobased column index. Must be between 0 (inclusive) and the
number of columns (exclusive).value
 The value to set at the given row and column in the matrix.java.lang.ArrayIndexOutOfBoundsException
 if the indices are out of boundspublic final void setElement(int rowIndex, int columnIndex, double value)
rowIndex
 Zerobased index into the rows of the MatrixcolumnIndex
 Zerobased index into the columns of the Matrixvalue
 Value to set at the specified indexjava.lang.ArrayIndexOutOfBoundsException
 if the indices are out of boundspublic final Matrix getSubMatrix(int minRow, int maxRow, int minColumn, int maxColumn)
minRow
 Zerobased index into the rows of the Matrix, must be less
than or equal to maxRowmaxRow
 Zerobased index into the rows of the Matrix, must be
greater than or equal to minRowminColumn
 Zerobased index into the rows of the Matrix, must be
less than or equal to maxColumnmaxColumn
 Zerobased index into the rows of the Matrix, must be
greater than or equal to minColumnjava.lang.ArrayIndexOutOfBoundsException
 if the input indices are outside
the acceptable boundspublic final boolean isSymmetric(double effectiveZero)
effectiveZero
 tolerance to determine symmetryjava.lang.IllegalArgumentException
 if effectiveZero less than zero.public final boolean isZero()
public final boolean isZero(double effectiveZero)
isZero
in interface Ring<Matrix>
isZero
in class AbstractMatrix
effectiveZero
 Tolerance threshold for elementwise equalityjava.lang.IllegalArgumentException
 if effectiveZero less than zero.public final Matrix transpose()
this
NOTE: Upon completion, this is in compressed Yale format. Returned sparse
matrix is in sparse vector format.this.getElement(i, j) == this.transpose().getElement(j, i)
for any valid i, j
.public final Matrix inverse()
this
, which must be a
square matrix
NOTE: Upon completion this is in the compressed Yale format.
This is implemented by creating a new dense matrix version of this and
calling its inverse method  inverting a sparse matrix is likely to
generate a dense matrix anyway. We would recommend using an iterative
solver (like Conjugate Gradient).this
, such that
this.times(this.inverse()) == this.inverse().times(this)
==
identity matrixpublic final Matrix pseudoInverse(double effectiveZero)
this
, using a
rather expensive procedure (SVD)
NOTE: Upon completion this is in the compressed Yale format.
This is implemented by creating a new dense matrix version of this and
calling its pseudoInverse method  inverting a sparse matrix is likely
to generate a dense matrix anyway. We would recommend using an iterative
solver (like Conjugate Gradient).effectiveZero
 effective zero to pass along to the SVDthis
public final ComplexNumber logDeterminant()
this
.
Very computationally intensive. Please THINK LONG AND HARD before
invoking this method on sparse matrices, as they have to be converted
to a DenseMatrix first.
NOTE: Upon completion this is in the compressed Yale format.
This is implemented by creating a new dense matrix version of this and
calling its logDeterminant method  It requires factoring the matrix
which is going to be memory intense anyway.this
public final int rank(double effectiveZero)
this
, which is the number of
linearly independent rows and columns in this
. Rank is
typically based on the SVD, which is a fairly computationally expensive
procedure and should be used carefully
NOTE: Upon completion this is in the compressed Yale format.
This is implemented by creating a new dense matrix version of this and
calling its rank method  It requires factoring the matrix which is
going to memory intense anyway.effectiveZero
 parameter to pass along to SVD to determine linear dependencethis
, equivalent to the number of linearly
indepenedent rows and columns in this
public double normFrobeniusSquared()
this
, which is just a
fancy way of saying that I will square each element and add those up.
NOTE: Upon completion this is in the compressed Yale format.this
public final double normFrobenius()
this
, which is just a fancy
way of saying that I will square each element, add those up, and square
root the result. This is probably the most intuitive of the matrix norms
NOTE: Upon completion this is in the compressed Yale format.this
public final boolean isSquare()
isSquare
in interface Matrix
isSquare
in class AbstractMatrix
public final Matrix solve(Matrix B)
B
 Must satisfy this.getNumColumns() == B.getNumRows();public final Vector solve(Vector b)
b
 must satisfy this.getNumColumns() == b.getDimensionality()public final void identity()
public final Vector getColumn(int columnIndex)
columnIndex
 zerobased index into the matrixpublic Vector sumOfColumns()
Matrix
sumOfColumns
in interface Matrix
sumOfColumns
in class AbstractMatrix
public Vector sumOfRows()
Matrix
sumOfRows
in interface Matrix
sumOfRows
in class AbstractMatrix
public final Vector getRow(int rowIndex)
rowIndex
 zerobased index into the matrixpublic final void convertFromVector(Vector parameters)
parameters
 columnstacked version of thisjava.lang.IllegalArgumentException
 if parameters does not have the same
number of elements as this's full size (including all of the zero
values).public final Vector convertToVector()
public java.util.Iterator<MatrixEntry> iterator()
iterator
in interface java.lang.Iterable<MatrixEntry>
@Deprecated public final java.util.Iterator<MatrixEntry> getNonZeroValueIterator()
public final java.util.Iterator<MatrixEntry> getNonZeroValueIterator(int startRow)
startRow
 The row to begin reading nonzero entries frompublic final Vector preTimes(SparseVector vector)
vector
 A sparse vector to multiply with thispublic final Vector preTimes(DenseVector vector)
vector
 A dense vector to multiply with thispublic MatrixFactory<?> getMatrixFactory()
Matrix
public final Matrix plus(Matrix other)
Ring
this
and other
public final Matrix minus(Matrix other)
Ring
other
from this
public final Matrix dotTimes(Matrix other)
Ring
this
and other
public final void plusEquals(Matrix other)
Ring
this
and other
plusEquals
in interface Ring<Matrix>
plusEquals
in class AbstractMatrix
other
 object to add to this
public final void scaledPlusEquals(double scaleFactor, Matrix other)
Ring
this
and other
after
elementwise 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.scaledPlusEquals
in interface Ring<Matrix>
scaledPlusEquals
in class AbstractMatrix
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.public final void minusEquals(Matrix other)
Ring
other
from
this
minusEquals
in interface Ring<Matrix>
minusEquals
in class AbstractMatrix
other
 object to subtract from this
public final void dotTimesEquals(Matrix other)
Ring
this
and
other
dotTimesEquals
in interface Ring<Matrix>
dotTimesEquals
in class AbstractMatrix
other
 elements of other will be multiplied to the corresponding
elements of this
public final Matrix times(Matrix other)
Matrix
this
and matrix
,
operates like the "*
" operator in Matlabtimes
in interface Matrix
times
in class AbstractMatrix
other
 this.getNumColumns()==matrix.getNumRows()
this
and
matrix
, will this.getNumRows()
rows and
matrix.getNumColumns()
columnspublic final Vector times(Vector vector)
Matrix
times
in interface Matrix
times
in class AbstractMatrix
vector
 Vector by which to postmultiply this, must have the
same number of rows as thispublic final Vector preTimes(Vector vector)
vector
 The vector to premultiply this byDimensionalityMismatchException
 if the input vectors's dimensions
doesn't match this's numRows.protected final void checkSubmatrixRange(int minRow, int maxRow, int minCol, int maxCol)
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)java.lang.ArrayIndexOutOfBoundsException
 if the input range is illegal or
outside the bounds of this.protected final void checkSolveDimensions(Vector b)
b
 The RHS vectorjava.lang.IllegalArgumentException
 if the input's size doesn't match this's
numRowsprotected final void checkSolveDimensions(Matrix b)
b
 The RHS matrixjava.lang.IllegalArgumentException
 if the input's size doesn't match this's
numRowspublic final java.lang.String toString(java.text.NumberFormat format)
Matrix
String
, using the given formatter.format
 The number format to use.