Matrix (Cognitive Foundry)

All Superinterfaces:

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

All Known Subinterfaces:

DiagonalMatrix

All Known Implementing Classes:

AbstractMatrix, AbstractMTJMatrix, AbstractSparseMatrix, DenseMatrix, DenseMatrix, DiagonalMatrix, DiagonalMatrixMTJ, ParallelSparseMatrix, SparseColumnMatrix, SparseMatrix, SparseMatrix, SparseRowMatrix
```
@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 java.lang.Iterable<MatrixEntry>, Ring<Matrix>, Vectorizable
```
Defines the base functionality for all implementations of a Matrix

Since:

1.0

Author:

Kevin R. Dixon

Method Summary

All Methods Instance Methods Abstract Methods
Modifier and Type	Method and Description
`void`	`assertMultiplicationDimensions(Matrix postMultiplicationMatrix)` Checks to see if the dimensions are appropriate for: `this.times(postMultiplicationMatrix)`.
`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)
`void`	`decrement(int row, int column)` Decrements the value at the given position by 1.
`void`	`decrement(int row, int column, double value)` Decrements the value at the given position by the given value.
`Matrix`	`dotDivide(Matrix other)` Element-wise division of `this` by `other`.
`void`	`dotDivideEquals(Matrix other)` Inline element-wise division of `this` by `other`.
`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.
`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.
`void`	`increment(int row, int column)` Increments the value at the given position by 1.
`void`	`increment(int row, int column, double value)` Increments the value at the given position by the given value.
`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.
`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`	`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`	`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`	`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.
`java.lang.String`	`toString()`
`java.lang.String`	`toString(java.text.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 diagonal elements.
`Matrix`	`transpose()` Returns the transpose of `this`
`java.util.List<java.lang.Double>`	`valuesAsList()` Returns a column-stacked view of this matrix as a list.

Methods inherited from interface java.lang.Iterable
forEach, iterator, spliterator

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
  - get
```
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.
    
    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.
    
    Since:
    
    3.4.0
  - set
```
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.
    
    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.
    
    Since:
    
    3.4.0
  - 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
  - assertMultiplicationDimensions
```
void assertMultiplicationDimensions(Matrix postMultiplicationMatrix)
```
    Checks to see if the dimensions are appropriate for: this.times(postMultiplicationMatrix).
    
    Parameters:
    
    postMultiplicationMatrix - Matrix by which this is to be multiplied.
  - 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 diagonal elements. It is equivalent to the sum of the eigenvalues (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
  - normFrobeniusSquared
```
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.
    
    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.
  - getEntryCount
```
int getEntryCount()
```
    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.
  - 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
  - increment
```
void increment(int row,
               int column)
```
    Increments the value at the given position by 1.
    
    Parameters:
    
    row - The zero-based row index.
    
    column - The zero-based column index.
  - increment
```
void increment(int row,
               int column,
               double value)
```
    Increments the value at the given position by the given value.
    
    Parameters:
    
    row - The zero-based row index.
    
    column - The zero-based column index.
    
    value - The value to add.
  - decrement
```
void decrement(int row,
               int column)
```
    Decrements the value at the given position by 1.
    
    Parameters:
    
    row - The zero-based row index.
    
    column - The zero-based column index.
  - decrement
```
void decrement(int row,
               int column,
               double value)
```
    Decrements the value at the given position by the given value.
    
    Parameters:
    
    row - The zero-based row index.
    
    column - The zero-based column index.
    
    value - The value to subtract.
  - 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.
  - valuesAsList
```
java.util.List<java.lang.Double> valuesAsList()
```
    Returns a column-stacked view of this matrix as a list. This means that v(k) = A(i,j) = v(j*M+i).
    
    Returns:
    
    The values in this matrix as a column-stacked list.
  - toString
```
java.lang.String toString()
```
    Overrides:
    
    toString in class java.lang.Object
  - toString
```
java.lang.String toString(java.text.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.
  - getMatrixFactory
```
MatrixFactory<?> getMatrixFactory()
```
    Gets a matrix factory, typically one associated with this type of matrix.
    
    Returns:
    
    A matrix factory.

Interface Matrix

Method Summary

Methods inherited from interface java.lang.Iterable

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

Method Detail

clone

getNumRows

getNumColumns

get

set

getElement

setElement

getSubMatrix

setSubMatrix

isSymmetric

isSymmetric

checkSameDimensions

assertSameDimensions

checkMultiplicationDimensions

assertMultiplicationDimensions

times

transpose

inverse

pseudoInverse

pseudoInverse

dotDivide

dotDivideEquals

logDeterminant

trace

rank

rank

normFrobenius

normFrobeniusSquared

isSquare

solve

solve

identity

times

isSparse

getEntryCount

getColumn

getRow

setColumn

setRow

sumOfRows

sumOfColumns

increment

increment

decrement

decrement

convertFromVector

convertToVector

toArray

valuesAsList

toString

toString

getMatrixFactory