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