SparseMatrix (Cognitive Foundry)

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

All Implemented Interfaces:

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

Direct Known Subclasses:

ParallelSparseMatrix
```
@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
```
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.

Since:

3.4.3

Author:

Jeremy D. Wendt

See Also:

Serialized Form

Field Summary

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

Constructor Summary

Constructors
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).

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
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 column-stacked vector of parameters, so that v(k) = A(i,j) = A( k%M, k/M )
`Vector`	`convertToVector()` Creates a column-stacked 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)` Element-wise multiplication of `this` and `other`
`void`	`dotTimesEquals(DenseMatrix other)` Type-specific version of dotTimesEquals for combining whatever type this is with the input dense matrix.
`void`	`dotTimesEquals(DiagonalMatrix other)` Type-specific version of dotTimesEquals for combining whatever type this is with the input diagonal matrix.
`void`	`dotTimesEquals(Matrix other)` Inline element-wise multiplication of `this` and `other`
`void`	`dotTimesEquals(SparseMatrix other)` Type-specific 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 zero-based row and column indices.
`Vector`	`getColumn(int columnIndex)` Gets the specified column from the zero-based index and returns a vector that corresponds to that column.
`double`	`getElement(int rowIndex, int columnIndex)` Gets the Matrix element at the specified zero-based indices throws ArrayIndexOutOfBoundsException if either rowIndex or columnIndex are less than 0, or greater than the number of rows (columns) minus one (0 <= index <= num-1)
`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 non-zero 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 zero-based 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, zero-based indices such that the result matrix will have size (maxRow-minRow+1) x (maxColum-minCcolumn+1)
`void`	`identity()` Formats the matrix as an identity matrix.
`Matrix`	`inverse()` Computes the full-blown 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 element-wise 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)` Type-specific version of minusEquals for combining whatever type this is with the input dense matrix.
`void`	`minusEquals(DiagonalMatrix other)` Type-specific 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)` Type-specific 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)` Type-specific version of plusEquals for combining whatever type this is with the input dense matrix.
`void`	`plusEquals(DiagonalMatrix other)` Type-specific 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)` Type-specific version of plusEquals for combining whatever type this is with the input sparse matrix.
`Vector`	`preTimes(DenseVector vector)` Type-specific version of pre-times for combining whatever type this is with the input dense vector.
`Matrix`	`preTimes(DiagonalMatrix other)` Package-private helper for the diagonal matrix class.
`Vector`	`preTimes(SparseVector vector)` Type-specific version of pre-times for combining whatever type this is with the input sparse vector.
`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?).
`Matrix`	`pseudoInverse(double effectiveZero)` Computes the effective pseudo-inverse 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)` Type-specific version of scaledPlusEquals for combining whatever type this is with the input dense matrix.
`void`	`scaledPlusEquals(DiagonalMatrix other, double scaleFactor)` Type-specific 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 element-wise scaling of `other` by `scaleFactor`.
`void`	`scaledPlusEquals(SparseMatrix other, double scaleFactor)` Type-specific version of scaledPlusEquals for combining whatever type this is with the input sparse matrix.
`void`	`scaleEquals(double scaleFactor)` Inline element-wise scaling of `this` by `scaleFactor`
`void`	`set(int rowIndex, int columnIndex, double value)` Sets the value of the element of the matrix at the zero-based row and column indices.
`void`	`setElement(int rowIndex, int columnIndex, double value)` Sets the Matrix element at the specified zero-based indices throws ArrayIndexOutOfBoundsException if either rowIndex or columnIndex are less than 0, or greater than the number of rows (columns) minus one (0 <= index <= num-1)
`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)` Type-specific version of times for combining whatever type this is with the input dense matrix.
`Vector`	`times(DenseVector vector)` Type-specific version of times for combining whatever type this is with the input dense vector.
`Matrix`	`times(DiagonalMatrix other)` Type-specific 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)` Type-specific version of times for combining whatever type this is with the input sparse matrix.
`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.
`Matrix`	`transpose()` Returns the transpose of `this`

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

- Field Detail
  - values
```
protected double[] values
```
    Part of the compressed Yale format. Generally only stores the non-zero elements of the matrix (to optimize some of the methods herein, some zero elements may be in vals). Will be null when the matrix is not compressed.
  - firstIndicesForRows
```
protected int[] firstIndicesForRows
```
    Part of the compressed Yale format. Stores the first index into vals for each row in the matrix. Has length of numRows + 1. Will be null when the matrix is not compressed.
  - columnIndices
```
protected int[] columnIndices
```
    Part of the compressed Yale format. Has the same length of vals. This specifies which column each element of vals is in. Will be null when the matrix is not compressed.
- Constructor Detail
  - SparseMatrix
```
public SparseMatrix(int numRows,
                    int numCols)
```
    Creates a new 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.
    
    Parameters:
    
    numRows - The number of rows in the matrix
    
    numCols - The number of columns in the matrix
  - SparseMatrix
```
public SparseMatrix(SparseMatrix 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
  - SparseMatrix
```
public SparseMatrix(DenseMatrix d)
```
    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
  - SparseMatrix
```
public SparseMatrix(DiagonalMatrix d)
```
    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
  - SparseMatrix
```
protected SparseMatrix()
```
    This should never be called by anything or anyone other than Java's serialization code.
- Method Detail
  - compress
```
public final 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. Note that the method will be automatically compressed and decompressed when various methods are called (e.g., decompressed for set* methods, compressed for times, dotTimes, etc.).
  - decompress
```
public final 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. Note that the method will be automatically compressed and decompressed when various methods are called (e.g., decompressed for set* methods, compressed for times, dotTimes, etc.).
  - isCompressed
```
public final boolean isCompressed()
```
    This method tests if the matrix is currently compressed to the compressed Yale format. Please note that the matrix gets compressed and decompressed as a side effect of various operations (including decompressed by set* calls and compressed by times, etc.). Therefore, don't be surprised if you call decompress, call some other methods and then find that it's compressed.
    
    Returns:
    
    true if this is compressed to the compressed Yale format, else false.
  - clone
```
public 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.
    
    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 AbstractRing<Matrix>
    
    Returns:
    
    A clone of this object.
  - isSparse
```
public boolean isSparse()
```
    Returns true if this matrix has a potentially sparse underlying structure. This can indicate that it is faster to only process the non-zero elements rather than to do dense operations on it. Of course, even with a sparse structure, there may be no zero elements or conversely even with a non-sparse (dense) structure there may be many zero elements. NOTE: This does not affect this's format.
    
    Returns:
    
    True if the matrix has a potentially sparse structure. Otherwise, false.
  - getEntryCount
```
public int getEntryCount()
```
    Description copied from interface: Matrix
    
    Gets the number of active entries in the matrix. Must be between 0 and the number of rows times the number of columns.
    
    Returns:
    
    The number of active entries in the matrix.
  - scaledPlusEquals
```
public void scaledPlusEquals(SparseMatrix other,
                             double scaleFactor)
```
    Type-specific version of scaledPlusEquals for combining whatever type this is with the input sparse matrix. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    other - A sparse matrix to add to this
    
    scaleFactor - The amount to scale other by
  - scaledPlusEquals
```
public void scaledPlusEquals(DenseMatrix other,
                             double scaleFactor)
```
    Type-specific version of scaledPlusEquals for combining whatever type this is with the input dense matrix. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    other - A dense matrix to add to this
    
    scaleFactor - The amount to scale other by
  - scaledPlusEquals
```
public void scaledPlusEquals(DiagonalMatrix other,
                             double scaleFactor)
```
    Type-specific version of scaledPlusEquals for combining whatever type this is with the input diagonal matrix. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    other - A diagonal matrix to add to this
    
    scaleFactor - The amount to scale other by
  - plusEquals
```
public final void plusEquals(SparseMatrix other)
```
    Type-specific version of plusEquals for combining whatever type this is with the input sparse matrix. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    other - A sparse matrix to add to this
  - plusEquals
```
public final void plusEquals(DenseMatrix other)
```
    Type-specific version of plusEquals for combining whatever type this is with the input dense matrix. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    other - A dense matrix to add to this
  - plusEquals
```
public final void plusEquals(DiagonalMatrix other)
```
    Type-specific version of plusEquals for combining whatever type this is with the input diagonal matrix. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    other - A diagonal matrix to add to this
  - minusEquals
```
public final void minusEquals(SparseMatrix other)
```
    Type-specific version of minusEquals for combining whatever type this is with the input sparse matrix. NOTE: Upon completion this and other are in the compressed Yale format.
    
    Parameters:
    
    other - A sparse matrix to subtract from this
  - minusEquals
```
public final void minusEquals(DenseMatrix other)
```
    Type-specific version of minusEquals for combining whatever type this is with the input dense matrix. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    other - A dense matrix to subtract from this
  - minusEquals
```
public final void minusEquals(DiagonalMatrix other)
```
    Type-specific version of minusEquals for combining whatever type this is with the input diagonal matrix. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    other - A diagonal matrix to subtract from this
  - dotTimesEquals
```
public final void dotTimesEquals(SparseMatrix other)
```
    Type-specific version of dotTimesEquals for combining whatever type this is with the input sparse matrix. NOTE: Upon completion this and other are in the compressed Yale format.
    
    Parameters:
    
    other - A sparse matrix to dot with this
  - dotTimesEquals
```
public final void dotTimesEquals(DenseMatrix other)
```
    Type-specific version of dotTimesEquals for combining whatever type this is with the input dense matrix. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    other - A dense matrix to dot with this
  - dotTimesEquals
```
public final void dotTimesEquals(DiagonalMatrix other)
```
    Type-specific version of dotTimesEquals for combining whatever type this is with the input diagonal matrix. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    other - A diagonal matrix to dot with this
  - times
```
public final Matrix times(SparseMatrix other)
```
    Type-specific version of times for combining whatever type this is with the input sparse matrix. This returns either a dense or a sparse matrix depending on the sparseness of the resulting multiplication NOTE: Upon completion this and other are in the compressed Yale format.
    
    Parameters:
    
    other - A sparse matrix to multiply with this
    
    Returns:
  - times
```
public final Matrix times(DenseMatrix other)
```
    Type-specific version of times for combining whatever type this is with the input dense matrix. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    other - A dense matrix to multiply with this
    
    Returns:
  - times
```
public final Matrix times(DiagonalMatrix other)
```
    Type-specific version of times for combining whatever type this is with the input diagonal matrix. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    other - A diagonal matrix to multiply with this
    
    Returns:
  - preTimes
```
public final Matrix preTimes(DiagonalMatrix other)
```
    Package-private helper for the diagonal matrix class. This handles diagonal*sparse calculation (so that sparse logic need not be embedded unnecessarily into the diagonal class). NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    other - The matrix to pre-multiply this by
    
    Returns:
    
    The sparse matrix (compressed Yale format) resulting from multiplying other * this.
  - 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.
    
    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.
    
    Parameters:
    
    vector - A dense vector to multiply with this
    
    Returns:
  - scaleEquals
```
public final void scaleEquals(double scaleFactor)
```
    Inline element-wise scaling of this by scaleFactor NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    scaleFactor - amount to scale the elements of this
  - getNumRows
```
public final int getNumRows()
```
    Returns the number of rows in the Matrix No change to compressed Yale or sparse row format.
    
    Returns:
    
    Number of rows in the Matrix
  - getNumColumns
```
public final int getNumColumns()
```
    Returns the number of columns in the Matrix No change to compressed Yale or sparse row format.
    
    Returns:
    
    Number of columns in the Matrix
  - get
```
public double get(int rowIndex,
                  int columnIndex)
```
    Gets the value of the element of the matrix at the zero-based row and column indices. It throws an ArrayIndexOutOfBoundsException if either index is out of range. It is a convenience method for getElement. No change to compressed Yale or sparse row format.
    
    Parameters:
    
    rowIndex - The zero-based row index. Must be between 0 (inclusive) and the number of rows (exclusive).
    
    columnIndex - The zero-based column index. Must be between 0 (inclusive) and the number of columns (exclusive).
    
    Returns:
    
    The value at the given row and column in the matrix.
  - getElement
```
public final double getElement(int rowIndex,
                               int columnIndex)
```
    Gets the Matrix element at the specified zero-based indices throws ArrayIndexOutOfBoundsException if either rowIndex or columnIndex are less than 0, or greater than the number of rows (columns) minus one (0 <= index <= num-1) No change to compressed Yale or sparse row format.
    
    Parameters:
    
    rowIndex - Zero-based index into the Matrix
    
    columnIndex - Zero-based index into the Matrix
    
    Returns:
    
    The value at rowIndex, columnIndex
  - set
```
public void set(int rowIndex,
                int columnIndex,
                double value)
```
    Sets the value of the element of the matrix at the zero-based row and column indices. It throws an ArrayIndexOutOfBoundsException if either index is out of range. It is a convenience method for setElement. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    rowIndex - The zero-based row index. Must be between 0 (inclusive) and the number of rows (exclusive).
    
    columnIndex - The zero-based 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.
    
    Throws:
    
    java.lang.ArrayIndexOutOfBoundsException - if the indices are out of bounds
  - setElement
```
public final void setElement(int rowIndex,
                             int columnIndex,
                             double value)
```
    Sets the Matrix element at the specified zero-based indices throws ArrayIndexOutOfBoundsException if either rowIndex or columnIndex are less than 0, or greater than the number of rows (columns) minus one (0 <= index <= num-1) NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    rowIndex - Zero-based index into the rows of the Matrix
    
    columnIndex - Zero-based index into the columns of the Matrix
    
    value - Value to set at the specified index
    
    Throws:
    
    java.lang.ArrayIndexOutOfBoundsException - if the indices are out of bounds
  - getSubMatrix
```
public final Matrix getSubMatrix(int minRow,
                                 int maxRow,
                                 int minColumn,
                                 int maxColumn)
```
    Gets the embedded submatrix inside of the Matrix, specified by the inclusive, zero-based indices such that the result matrix will have size (maxRow-minRow+1) x (maxColum-minCcolumn+1) NOTE: Upon completion, this is in compressed Yale format. Return value is also in compressed Yale format.
    
    Parameters:
    
    minRow - Zero-based index into the rows of the Matrix, must be less than or equal to maxRow
    
    maxRow - Zero-based index into the rows of the Matrix, must be greater than or equal to minRow
    
    minColumn - Zero-based index into the rows of the Matrix, must be less than or equal to maxColumn
    
    maxColumn - Zero-based index into the rows of the Matrix, must be greater than or equal to minColumn
    
    Returns:
    
    the Matrix of dimension (maxRow-minRow+1)x(maxColumn-minColumn+1)
    
    Throws:
    
    java.lang.ArrayIndexOutOfBoundsException - if the input indices are outside the acceptable bounds
  - isSymmetric
```
public final boolean isSymmetric(double effectiveZero)
```
    Determines if the matrix is effectively symmetric NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    effectiveZero - tolerance to determine symmetry
    
    Returns:
    
    true if effectively symmetric, false otherwise
    
    Throws:
    
    java.lang.IllegalArgumentException - if effectiveZero less than zero.
  - isZero
```
public final boolean isZero()
```
    Determines if this ring is equal to zero. NOTE: Upon completion this is in the compressed Yale format.
    
    Specified by:
    
    isZero in interface Ring<Matrix>
    
    Overrides:
    
    isZero in class AbstractRing<Matrix>
    
    Returns:
    
    True if all of the elements of this ring are zero.
  - isZero
```
public final boolean isZero(double effectiveZero)
```
    Determines if this ring is equal to zero using the element-wise effective zero value. NOTE: Upon completion this is in the compressed Yale format.
    
    Specified by:
    
    isZero in interface Ring<Matrix>
    
    Overrides:
    
    isZero in class AbstractMatrix
    
    Parameters:
    
    effectiveZero - Tolerance threshold for element-wise equality
    
    Returns:
    
    True if all of the elements of this ring are effectively zero.
    
    Throws:
    
    java.lang.IllegalArgumentException - if effectiveZero less than zero.
  - transpose
```
public final Matrix transpose()
```
    Returns the transpose of this NOTE: Upon completion, this is in compressed Yale format. Returned sparse matrix is in sparse vector format.
    
    Returns:
    
    Matrix whose elements are equivalent to: this.getElement(i, j) == this.transpose().getElement(j, i) for any valid i, j.
  - inverse
```
public final Matrix inverse()
```
    Computes the full-blown inverse of 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).
    
    Returns:
    
    Inverse of this, such that this.times(this.inverse()) == this.inverse().times(this) ==identity matrix
  - pseudoInverse
```
public final Matrix pseudoInverse(double effectiveZero)
```
    Computes the effective pseudo-inverse of 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).
    
    Parameters:
    
    effectiveZero - effective zero to pass along to the SVD
    
    Returns:
    
    effective pseudo-inverse of this
  - logDeterminant
```
public final ComplexNumber logDeterminant()
```
    Computes the natural logarithm of the determinant of 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.
    
    Returns:
    
    natural logarithm of the determinant of this
  - rank
```
public final int rank(double effectiveZero)
```
    Computes the effective rank of 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.
    
    Parameters:
    
    effectiveZero - parameter to pass along to SVD to determine linear dependence
    
    Returns:
    
    rank of this, equivalent to the number of linearly indepenedent rows and columns in this
  - normFrobeniusSquared
```
public 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. NOTE: Upon completion this is in the compressed Yale format.
    
    Returns:
    
    Frobenius norm of this
  - normFrobenius
```
public final 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. This is probably the most intuitive of the matrix norms NOTE: Upon completion this is in the compressed Yale format.
    
    Returns:
    
    Frobenius norm of this
  - isSquare
```
public final boolean isSquare()
```
    Determines if the matrix is square (numRows == numColumns) NOTE: No change to the internal format of this.
    
    Specified by:
    
    isSquare in interface Matrix
    
    Overrides:
    
    isSquare in class AbstractMatrix
    
    Returns:
    
    true if square, false if nonsquare
  - solve
```
public final Matrix solve(Matrix B)
```
    Solves for "X" in the equation: this*X = B 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 solve method -- It requires factoring the matrix which is going to memory intense anyway. We recommend an iterative solver instead.
    
    Parameters:
    
    B - Must satisfy this.getNumColumns() == B.getNumRows();
    
    Returns:
    
    X Matrix with dimensions (this.getNumColumns() x B.getNumColumns())
  - solve
```
public final Vector solve(Vector b)
```
    Solves for "x" in the equation: this*x = b 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 solve method -- It requires factoring the matrix which is going to memory intense anyway. We recommend an iterative solver instead.
    
    Parameters:
    
    b - must satisfy this.getNumColumns() == b.getDimensionality()
    
    Returns:
    
    x Vector with dimensions (this.getNumColumns())
  - identity
```
public final void identity()
```
    Formats the matrix as an identity matrix. This does not have to be square. NOTE: Upon completion this is in the compressed Yale format.
  - getColumn
```
public final Vector getColumn(int columnIndex)
```
    Gets the specified column from the zero-based index and returns a vector that corresponds to that column. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    columnIndex - zero-based index into the matrix
    
    Returns:
    
    Vector with elements equal to the number of rows in this
  - sumOfColumns
```
public Vector sumOfColumns()
```
    Description copied from interface: Matrix
    
    Returns a new vector containing the sum across the columns.
    
    Specified by:
    
    sumOfColumns in interface Matrix
    
    Overrides:
    
    sumOfColumns in class AbstractMatrix
    
    Returns:
    
    A new vector containing the sum of the columns. Its dimensionality is equal to the number of rows.
  - sumOfRows
```
public Vector sumOfRows()
```
    Description copied from interface: Matrix
    
    Returns a new vector containing the sum across the rows.
    
    Specified by:
    
    sumOfRows in interface Matrix
    
    Overrides:
    
    sumOfRows in class AbstractMatrix
    
    Returns:
    
    A new vector containing the sum of the rows. Its dimensionality is equal to the number of columns.
  - getRow
```
public final Vector getRow(int rowIndex)
```
    Gets the specified row from the zero-based index and returns a vector that corresponds to that column NOTE: Internal format is unchanged after this method.
    
    Parameters:
    
    rowIndex - zero-based index into the matrix
    
    Returns:
    
    Vector with elements equal to the number of columns in this
  - convertFromVector
```
public final void convertFromVector(Vector parameters)
```
    uploads a matrix from a column-stacked vector of parameters, so that v(k) = A(i,j) = A( k%M, k/M ) NOTE: Upon ocmpletion this is in the compressed Yale format.
    
    Parameters:
    
    parameters - column-stacked version of this
    
    Throws:
    
    java.lang.IllegalArgumentException - if parameters does not have the same number of elements as this's full size (including all of the zero values).
  - convertToVector
```
public final Vector convertToVector()
```
    Creates a column-stacked version of this, so that v(k) = A(i,j) = v(j*M+i) NOTE: This does not affect compressed Yale/sparse row representation -- either is handled.
    
    Returns:
    
    column-stacked Vector representing this
  - iterator
```
public java.util.Iterator<MatrixEntry> iterator()
```
    Specified by:
    
    iterator in interface java.lang.Iterable<MatrixEntry>
  - getNonZeroValueIterator
```
@Deprecated
public final java.util.Iterator<MatrixEntry> getNonZeroValueIterator()
```
    Deprecated.
    
    Returns an iterator over the non-zero entries in this matrix. The returned iterator is invalidated by any subsequent changes to the referenced matrix. Any follow-on calls to the iterator after any changes to the referred instance will provide undefined results (up to and including throwing Exceptions).
    
    Returns:
    
    an iterator over the non-zero entries in this matrix (left-to-right, top-to-bottom).
  - getNonZeroValueIterator
```
public final java.util.Iterator<MatrixEntry> getNonZeroValueIterator(int startRow)
```
    Returns an iterator over the non-zero entries in this matrix starting with startRow. The returned iterator is invalidated by any subsequent changes to the referenced matrix. Any follow-on calls to the iterator after any changes to the referred instance will provide undefined results (up to and including throwing Exceptions).
    
    Parameters:
    
    startRow - The row to begin reading non-zero entries from
    
    Returns:
    
    an iterator over the non-zero entries in this matrix (left-to-right, top-to-bottom).
  - preTimes
```
public final Vector preTimes(SparseVector vector)
```
    Type-specific version of pre-times for combining whatever type this is with the input sparse vector. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    vector - A sparse vector to multiply with this
    
    Returns:
  - preTimes
```
public final Vector preTimes(DenseVector vector)
```
    Type-specific version of pre-times for combining whatever type this is with the input dense vector. NOTE: Upon completion this is in the compressed Yale format.
    
    Parameters:
    
    vector - A dense vector to multiply with this
    
    Returns:
  - getMatrixFactory
```
public MatrixFactory<?> getMatrixFactory()
```
    Description copied from interface: Matrix
    
    Gets a matrix factory, typically one associated with this type of matrix.
    
    Returns:
    
    A matrix factory.
  - 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.

Class SparseMatrix

Field Summary

Constructor Summary

Method Summary

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

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

Methods inherited from class java.lang.Object

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

Methods inherited from interface java.lang.Iterable

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

Field Detail

values

firstIndicesForRows

columnIndices

Constructor Detail

SparseMatrix

SparseMatrix

SparseMatrix

SparseMatrix

SparseMatrix

Method Detail

compress

decompress

isCompressed

clone

isSparse

getEntryCount

scaledPlusEquals

scaledPlusEquals

scaledPlusEquals

plusEquals

plusEquals

plusEquals

minusEquals

minusEquals

minusEquals

dotTimesEquals

dotTimesEquals

dotTimesEquals

times

times

times

preTimes

times

times

scaleEquals

getNumRows

getNumColumns

get

getElement

set

setElement

getSubMatrix

isSymmetric

isZero

isZero

transpose

inverse

pseudoInverse

logDeterminant

rank

normFrobeniusSquared

normFrobenius

isSquare

solve

solve

identity

getColumn

sumOfColumns

sumOfRows

getRow

convertFromVector

convertToVector

iterator

getNonZeroValueIterator

getNonZeroValueIterator

preTimes

preTimes

getMatrixFactory

plus