gov.sandia.cognition.math.matrix
Interface Matrix

All Superinterfaces:
Cloneable, CloneableSerializable, Iterable<MatrixEntry>, Ring<Matrix>, Serializable, Vectorizable
All Known Subinterfaces:
DiagonalMatrix
All Known Implementing Classes:
AbstractMatrix, AbstractMTJMatrix, AbstractSparseMatrix, DenseMatrix, DiagonalMatrixMTJ, SparseColumnMatrix, SparseMatrix, SparseRowMatrix

@CodeReviews(reviews={@CodeReview(reviewer="Kevin R. Dixon",date="2008-02-26",changesNeeded=false,comments={"Minor changes to the formatting","Otherwise, looks good."}),@CodeReview(reviewer="Jonathan McClain",date="2006-05-16",changesNeeded=false,comments="Interface looks ok. Made a few minor changes.")})
public interface Matrix
extends Iterable<MatrixEntry>, Ring<Matrix>, Vectorizable

Defines the base functionality for all implementations of a Matrix

Since:
1.0
Author:
Kevin R. Dixon

Method Summary
 void assertSameDimensions(Matrix otherMatrix)
          Throws a DimensionalityMismatchException if dimensions between this and otherMatrix aren't the same
 boolean checkMultiplicationDimensions(Matrix postMultiplicationMatrix)
          Checks to see if the dimensions are appropriate for: this.times( postMultiplicationMatrix )
 boolean checkSameDimensions(Matrix otherMatrix)
          Checks to see if the dimensions are the same between this and otherMatrix
 Matrix clone()
          Returns a smart copy of this, such that changing the values of the return class will not effect this
 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)
 Matrix dotDivide(Matrix other)
          Element-wise division of this by other.
 void dotDivideEquals(Matrix other)
          Inline element-wise division of this by other.
 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 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 isSparse()
          Returns true if this matrix has a potentially sparse underlying structure.
 boolean isSquare()
          Determines if the matrix is square (numRows == numColumns)
 boolean isSymmetric()
          Determines if the matrix is symmetric.
 boolean isSymmetric(double effectiveZero)
          Determines if the matrix is effectively symmetric
 ComplexNumber logDeterminant()
          Computes the natural logarithm of the determinant of this.
 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.
 Matrix pseudoInverse()
          Computes the effective pseudo-inverse of this, using a rather expensive procedure (SVD)
 Matrix pseudoInverse(double effectiveZero)
          Computes the effective pseudo-inverse of this, using a rather expensive procedure (SVD)
 int rank()
          Computes the rank of this, which is the number of linearly independent rows and columns in this.
 int rank(double effectiveZero)
          Computes the effective rank of this, which is the number of linearly independent rows and columns in this.
 void setColumn(int columnIndex, Vector columnVector)
          Sets the specified column from the given columnVector
 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)
 void setRow(int rowIndex, Vector rowVector)
          Sets the specified row from the given rowVector
 void setSubMatrix(int minRow, int minColumn, Matrix submatrix)
          Sets the submatrix inside of the Matrix, specified by the zero-based indices.
 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(Matrix matrix)
          Matrix multiplication of this and matrix, operates like the "*" operator in Matlab
 Vector times(Vector vector)
          Returns the column vector from the equation return = this * vector
 double[][] toArray()
          Converts this matrix to a new array of array of doubles, in the same order as they are in the matrix.
 String toString()
           
 String toString(NumberFormat format)
          Converts the vector to a String, using the given formatter.
 double trace()
          Computes the trace of this, which is the sum of the eigenvalues and if equivalent to the sum of the diagonal element (which is probably the most interesting result in all of algebra!!)
 Matrix transpose()
          Returns the transpose of this
 
Methods inherited from interface java.lang.Iterable
iterator
 
Methods inherited from interface gov.sandia.cognition.math.Ring
dotTimes, dotTimesEquals, equals, equals, isZero, isZero, minus, minusEquals, negative, negativeEquals, plus, plusEquals, scale, scaledMinus, scaledMinusEquals, scaledPlus, scaledPlusEquals, scaleEquals, zero
 

Method Detail

clone

Matrix clone()
Description copied from interface: Ring
Returns a smart copy of this, such that changing the values of the return class will not effect this

Specified by:
clone in interface CloneableSerializable
Specified by:
clone in interface Ring<Matrix>
Specified by:
clone in interface Vectorizable
Returns:
smart copy of this

getNumRows

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

Returns:
Number of rows in the Matrix

getNumColumns

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

Returns:
Number of columns in the Matrix

getElement

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)

Parameters:
rowIndex - Zero-based index into the Matrix
columnIndex - Zero-based index into the Matrix
Returns:
The value at rowIndex, columnIndex

setElement

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)

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

getSubMatrix

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)

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)

setSubMatrix

void setSubMatrix(int minRow,
                  int minColumn,
                  Matrix submatrix)
Sets the submatrix inside of the Matrix, specified by the zero-based indices.

Parameters:
minRow - Zero-based index into the rows of the Matrix, must be less than or equal to maxRow
minColumn - Zero-based index into the rows of the Matrix, must be less than or equal to maxColumn
submatrix - Matrix containing the values to set at the specified indices

isSymmetric

boolean isSymmetric()
Determines if the matrix is symmetric.

Returns:
true if the matrix is symmetric, false otherwise

isSymmetric

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

Parameters:
effectiveZero - tolerance to determine symmetry
Returns:
true if effectively symmetric, false otherwise

checkSameDimensions

boolean checkSameDimensions(Matrix otherMatrix)
Checks to see if the dimensions are the same between this and otherMatrix

Parameters:
otherMatrix - matrix against which to check
Returns:
true if this.getNumRows() == otherMatrix.getNumRows() and this.getNumColumns() == otherMatrix.getNumColumns()

assertSameDimensions

void assertSameDimensions(Matrix otherMatrix)
Throws a DimensionalityMismatchException if dimensions between this and otherMatrix aren't the same

Parameters:
otherMatrix - Matrix dimensions to compare to this

checkMultiplicationDimensions

boolean checkMultiplicationDimensions(Matrix postMultiplicationMatrix)
Checks to see if the dimensions are appropriate for: this.times( postMultiplicationMatrix )

Parameters:
postMultiplicationMatrix - matrix by which this is to be multiplied
Returns:
true if this.getNumColumns() == postMultlicationMatrix.getNumColumns(), false otherwise

times

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

Parameters:
matrix - this.getNumColumns()==matrix.getNumRows()
Returns:
Matrix multiplication of this and matrix, will this.getNumRows() rows and matrix.getNumColumns() columns

transpose

Matrix transpose()
Returns the transpose of this

Returns:
Matrix whose elements are equivalent to: this.getElement(i, j) == this.transpose().getElement(j, i) for any valid i, j.

inverse

Matrix inverse()
Computes the full-blown inverse of this, which must be a square matrix

Returns:
Inverse of this, such that this.times(this.inverse()) == this.inverse().times(this) == identity matrix

pseudoInverse

Matrix pseudoInverse()
Computes the effective pseudo-inverse of this, using a rather expensive procedure (SVD)

Returns:
full singular-value pseudo-inverse of this

pseudoInverse

Matrix pseudoInverse(double effectiveZero)
Computes the effective pseudo-inverse of this, using a rather expensive procedure (SVD)

Parameters:
effectiveZero - effective zero to pass along to the SVD
Returns:
effective pseudo-inverse of this

dotDivide

Matrix dotDivide(Matrix other)
Element-wise division of this by other. Note that if other has zero elements the result will contain NaN values.

Parameters:
other - The other ring whose elements will divide into this one.
Returns:
A new ring of equal size whose elements are equal to the corresponding element in this divided by the element in other.

dotDivideEquals

void dotDivideEquals(Matrix other)
Inline element-wise division of this by other. Note that if other has zero elements this will contain NaN values.

Parameters:
other - The other vector whose elements will divide into this one.

logDeterminant

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.

Returns:
natural logarithm of the determinant of this

trace

double trace()
Computes the trace of this, which is the sum of the eigenvalues and if equivalent to the sum of the diagonal element (which is probably the most interesting result in all of algebra!!)

Returns:
trace of this

rank

int rank()
Computes the 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

Returns:
rank of this, equivalent to the number of linearly independent rows and columns in this

rank

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

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

normFrobenius

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

Returns:
Frobenius norm of this

isSquare

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

Returns:
true if square, false if nonsquare

solve

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

Parameters:
B - Must satisfy this.getNumColumns() == B.getNumRows();
Returns:
X Matrix with dimensions (this.getNumColumns() x B.getNumColumns())

solve

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

Parameters:
b - must satisfy this.getNumColumns() == b.getDimensionality()
Returns:
x Vector with dimensions (this.getNumColumns())

identity

void identity()
Formats the matrix as an identity matrix. This does not have to be square.


times

Vector times(Vector vector)
Returns the column vector from the equation return = this * vector

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

isSparse

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.

Returns:
True if the matrix has a potentially sparse structure. Otherwise, false.

getColumn

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

Parameters:
columnIndex - zero-based index into the matrix
Returns:
Vector with elements equal to the number of rows in this

getRow

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

Parameters:
rowIndex - zero-based index into the matrix
Returns:
Vector with elements equal to the number of columns in this

setColumn

void setColumn(int columnIndex,
               Vector columnVector)
Sets the specified column from the given columnVector

Parameters:
columnIndex - zero-based index into the matrix
columnVector - vector to replace in this, must have same number of elements as this has rows

setRow

void setRow(int rowIndex,
            Vector rowVector)
Sets the specified row from the given rowVector

Parameters:
rowIndex - zero-based index into the matrix
rowVector - vector to replace in this, must have the same number of elements as this has columns

sumOfRows

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

Returns:
A new vector containing the sum of the rows. Its dimensionality is equal to the number of columns.
Since:
3.0

sumOfColumns

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

Returns:
A new vector containing the sum of the columns. Its dimensionality is equal to the number of rows.
Since:
3.0

convertFromVector

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 )

Specified by:
convertFromVector in interface Vectorizable
Parameters:
parameters - column-stacked version of this

convertToVector

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

Specified by:
convertToVector in interface Vectorizable
Returns:
column-stacked Vector representing this

toArray

double[][] toArray()
Converts this matrix to a new array of array of doubles, in the same order as they are in the matrix. The returned will be safe in that no references are maintained by this class.

Returns:
This matrix as a dense array. The length of the first layer of the array will be equal to the number of rows and the second layer will be equal to the number of columns.

toString

String toString()
Overrides:
toString in class Object

toString

String toString(NumberFormat format)
Converts the vector to a String, using the given formatter.

Parameters:
format - The number format to use.
Returns:
The String representation of the Matrix.