gov.sandia.cognition.math.matrix.mtj
Class AbstractMTJMatrix

java.lang.Object
  extended by gov.sandia.cognition.util.AbstractCloneableSerializable
      extended by gov.sandia.cognition.math.AbstractRing<Matrix>
          extended by gov.sandia.cognition.math.matrix.AbstractMatrix
              extended by gov.sandia.cognition.math.matrix.mtj.AbstractMTJMatrix
All Implemented Interfaces:
Matrix, Vectorizable, Ring<Matrix>, CloneableSerializable, Serializable, Cloneable, Iterable<MatrixEntry>
Direct Known Subclasses:
AbstractSparseMatrix, DenseMatrix, DiagonalMatrixMTJ

@CodeReview(reviewer="Jonathan McClain",
            date="2006-05-18",
            changesNeeded=true,
            comments="Comments marked throughout the file with / / / on first column.",
            response=@CodeReviewResponse(respondent="Kevin R. Dixon",date="2006-05-18",moreChangesNeeded=false,comments={"Added an assertion to dotTimesEquals","Commented the private classes so that they\'re up to snuff."}))
@PublicationReference(author="Bjorn-Ove Heimsund",
                      title="Matrix Toolkits for Java (MTJ)",
                      type=WebPage,
                      year=2006,
                      url="http://ressim.berlios.de/",
                      notes="All subclasses essentially wrap one of MTJ\'s matrix classes.")
@SoftwareReference(name="Matrix Toolkits for Java (MTJ)",
                   version="0.9.6",
                   url="http://ressim.berlios.de/",
                   license=LGPL,
                   licenseVersion="2.1",
                   licenseURL="http://ressim.berlios.de/")
public abstract class AbstractMTJMatrix
extends AbstractMatrix

Relies on internal MTJ matrix to do some of the heavy lifting, without assuming that the underlying matrix is Dense or Sparse

Since:
1.0
Author:
Kevin R. Dixon
See Also:
Serialized Form

Constructor Summary
protected AbstractMTJMatrix(no.uib.cipr.matrix.Matrix internalMatrix)
          Creates a new instance of AbstractMTJMatrix
 
Method Summary
 AbstractMTJMatrix clone()
          This makes public the clone method on the Object class and removes the exception that it throws.
 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 )
 DenseVector convertToVector()
          Creates a column-stacked version of this, so that v(k) = A(i,j) = v(j*M+i)
 void dotTimesEquals(AbstractMTJMatrix matrix)
          Inline element-wise multiplication of the elements in this and matrix, modifies the elements of this
 void dotTimesEquals(Matrix matrix)
          Inline element-wise multiplication of this and other
 boolean equals(AbstractMTJMatrix matrix, double effectiveZero)
          Determines if the matrices are effectively equal to each other
 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.uib.cipr.matrix.Matrix getInternalMatrix()
          Gets the internal MTJ matrix that this class is wrapping.
 int getNumColumns()
          Returns the number of columns in the Matrix
 int getNumRows()
          Returns the number of rows in the Matrix
protected  void getSubMatrixInto(int minRow, int maxRow, int minColumn, int maxColumn, AbstractMTJMatrix destinationMatrix)
          Internal routine for storing a submatrix into and AbstractMTJMatrix.
 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 isSquare()
          Determines if the matrix is square (numRows == numColumns)
 boolean isSymmetric(double effectiveZero)
          Determines if the matrix is effectively symmetric
 Iterator<MatrixEntry> iterator()
           
 ComplexNumber logDeterminant()
          Computes the natural logarithm of the determinant of this.
 void minusEquals(AbstractMTJMatrix matrix)
          Subtracts the elements of matrix from the elements of this, modifies the elements of this
 void minusEquals(Matrix matrix)
          Inline arithmetic subtraction of other from 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.
 void plusEquals(AbstractMTJMatrix matrix)
          Inline addition of this and matrix, modifies the elements of this
 void plusEquals(Matrix matrix)
          Inline arithmetic addition of this and other
 int rank(double effectiveZero)
          Computes the effective rank of this, which is the number of linearly independent rows and columns in this.
 void scaledMinusEquals(double scaleFactor, AbstractMTJMatrix other)
          Subtracts from this matrix the scaled version of the other given matrix.
 void scaledPlusEquals(double scaleFactor, AbstractMTJMatrix other)
          Adds to this vector the scaled version of the other given vector.
 void scaledPlusEquals(double scaleFactor, Matrix other)
          Inline arithmetic addition of this and other after element-wise scaling of other by scaleFactor.
 void scaleEquals(double scaleFactor)
          Inline element-wise scaling of this by scaleFactor
 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)
protected  void setInternalMatrix(no.uib.cipr.matrix.Matrix internalMatrix)
          Setter for internalMatrix
 Matrix solve(AbstractMTJMatrix B)
          Solves for "X" in the equation this * X = B, where X is a DenseMatrix, "this" and "B" will be converted to a DenseMatrix (if not already)
 Vector solve(AbstractMTJVector b)
          Solves for "x" in the equation: this*x = b
 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
abstract  AbstractMTJMatrix times(AbstractMTJMatrix matrix)
          Matrix multiplication of this and matrix, operates like the "*" operator in Matlab
abstract  AbstractMTJVector times(AbstractMTJVector vector)
          Returns the column vector from the equation return = this * vector
 AbstractMTJMatrix times(Matrix matrix)
          Matrix multiplication of this and matrix, operates like the "*" operator in Matlab
 AbstractMTJVector times(Vector vector)
          Returns the column vector from the equation return = this * vector
protected  void timesInto(AbstractMTJMatrix multiplicationMatrix, AbstractMTJMatrix destinationMatrix)
          Internal function call that stores the result of a matrix multiply into the given destinationMatrix.
protected  void timesInto(AbstractMTJVector multiplicationVector, AbstractMTJVector destinationVector)
          Internal function call that stores the result of a matrix multiply into the given destinationVector.
protected  void transposeInto(AbstractMTJMatrix destinationMatrix)
          Internal method for accessing MTJ's general transpose routine
 void zero()
          Zeros out all elements of this, so that the following are equivalent r1.scaleEquals( 0.0 ); and r1.zero(); Furthermore, r1.zero(); anything.dotTimes( r1 ).equals( r1 );
 
Methods inherited from class gov.sandia.cognition.math.matrix.AbstractMatrix
assertSameDimensions, checkMultiplicationDimensions, checkSameDimensions, dotDivide, dotDivideEquals, equals, equals, getColumnInto, getRowInto, hashCode, isSymmetric, isZero, pseudoInverse, rank, setColumn, setRow, setSubMatrix, sumOfColumns, sumOfRows, toArray, trace
 
Methods inherited from class gov.sandia.cognition.math.AbstractRing
dotTimes, isZero, minus, negative, negativeEquals, plus, scale, scaledMinus, scaledMinusEquals, scaledPlus
 
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
getColumn, getRow, getSubMatrix, isSparse, pseudoInverse, toString, toString, transpose
 
Methods inherited from interface gov.sandia.cognition.math.Ring
dotTimes, isZero, minus, negative, negativeEquals, plus, scale, scaledMinus, scaledMinusEquals, scaledPlus
 

Constructor Detail

AbstractMTJMatrix

protected AbstractMTJMatrix(no.uib.cipr.matrix.Matrix internalMatrix)
Creates a new instance of AbstractMTJMatrix

Parameters:
internalMatrix - MTJ-based matrix to store inside of this
Method Detail

clone

public AbstractMTJMatrix clone()
Description copied from class: AbstractCloneableSerializable
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.

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.

getInternalMatrix

public no.uib.cipr.matrix.Matrix getInternalMatrix()
Gets the internal MTJ matrix that this class is wrapping.

Returns:
Internal MTJ matrix.

setInternalMatrix

protected void setInternalMatrix(no.uib.cipr.matrix.Matrix internalMatrix)
Setter for internalMatrix

Parameters:
internalMatrix - internal MTJ-based matrix

getNumRows

public int getNumRows()
Description copied from interface: Matrix
Returns the number of rows in the Matrix

Returns:
Number of rows in the Matrix

getNumColumns

public int getNumColumns()
Description copied from interface: Matrix
Returns the number of columns in the Matrix

Returns:
Number of columns in the Matrix

getElement

public double getElement(int rowIndex,
                         int columnIndex)
Description copied from interface: Matrix
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

public void setElement(int rowIndex,
                       int columnIndex,
                       double value)
Description copied from interface: Matrix
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

logDeterminant

public ComplexNumber logDeterminant()
Description copied from interface: Matrix
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

equals

public boolean equals(AbstractMTJMatrix matrix,
                      double effectiveZero)
Determines if the matrices are effectively equal to each other

Parameters:
matrix - Matrix to compare this to, must be same size as this
effectiveZero - tolerance to determine element-wise equality
Returns:
true if effectively equal, false otherwise

plusEquals

public void plusEquals(Matrix matrix)
Description copied from interface: Ring
Inline arithmetic addition of this and other

Parameters:
matrix - object to add to this

plusEquals

public void plusEquals(AbstractMTJMatrix matrix)
Inline addition of this and matrix, modifies the elements of this

Parameters:
matrix - Must have same dimensions this

minusEquals

public void minusEquals(Matrix matrix)
Description copied from interface: Ring
Inline arithmetic subtraction of other from this

Parameters:
matrix - object to subtract from this

minusEquals

public void minusEquals(AbstractMTJMatrix matrix)
Subtracts the elements of matrix from the elements of this, modifies the elements of this

Parameters:
matrix - Must have same dimensions this

times

public AbstractMTJMatrix times(Matrix matrix)
Description copied from interface: 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

times

public abstract AbstractMTJMatrix times(AbstractMTJMatrix 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

dotTimesEquals

public void dotTimesEquals(Matrix matrix)
Description copied from interface: Ring
Inline element-wise multiplication of this and other

Parameters:
matrix - elements of other will be multiplied to the corresponding elements of this

dotTimesEquals

public void dotTimesEquals(AbstractMTJMatrix matrix)
Inline element-wise multiplication of the elements in this and matrix, modifies the elements of this

Parameters:
matrix - Must have same dimensions this

scaleEquals

public void scaleEquals(double scaleFactor)
Description copied from interface: Ring
Inline element-wise scaling of this by scaleFactor

Parameters:
scaleFactor - amount to scale the elements of this

scaledPlusEquals

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

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.

scaledPlusEquals

public void scaledPlusEquals(double scaleFactor,
                             AbstractMTJMatrix other)
Adds to this vector the scaled version of the other given vector.

Parameters:
scaleFactor - The scale factor to use.
other - The other vector to scale and then add to this vector.

scaledMinusEquals

public void scaledMinusEquals(double scaleFactor,
                              AbstractMTJMatrix other)
Subtracts from this matrix the scaled version of the other given matrix.

Parameters:
scaleFactor - The scale factor to use.
other - The other matrix to scale and then subtract from this matrix.

iterator

public Iterator<MatrixEntry> iterator()

isSquare

public boolean isSquare()
Description copied from interface: Matrix
Determines if the matrix is square (numRows == numColumns)

Returns:
true if square, false if nonsquare

times

public AbstractMTJVector times(Vector vector)
Description copied from interface: Matrix
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

times

public abstract AbstractMTJVector times(AbstractMTJVector 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

identity

public void identity()
Description copied from interface: Matrix
Formats the matrix as an identity matrix. This does not have to be square.


solve

public Matrix solve(Matrix B)
Description copied from interface: Matrix
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

public Vector solve(Vector b)
Description copied from interface: Matrix
Solves for "x" in the equation: this*x = b

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

solve

public final Matrix solve(AbstractMTJMatrix B)
Solves for "X" in the equation this * X = B, where X is a DenseMatrix, "this" and "B" will be converted to a DenseMatrix (if not already)

Parameters:
B - AbstractMTJMatrix, will be converted to a DenseMatrix
Returns:
DenseMatrix of "X" in this * X = B

solve

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

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

inverse

public Matrix inverse()
Description copied from interface: Matrix
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

normFrobenius

public double normFrobenius()
Description copied from interface: Matrix
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

isSymmetric

public boolean isSymmetric(double effectiveZero)
Description copied from interface: Matrix
Determines if the matrix is effectively symmetric

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

zero

public void zero()
Description copied from interface: Ring
Zeros out all elements of this, so that the following are equivalent r1.scaleEquals( 0.0 ); and r1.zero(); Furthermore, r1.zero(); anything.dotTimes( r1 ).equals( r1 );

Specified by:
zero in interface Ring<Matrix>
Overrides:
zero in class AbstractRing<Matrix>

rank

public int rank(double effectiveZero)
Description copied from interface: Matrix
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

transposeInto

protected void transposeInto(AbstractMTJMatrix destinationMatrix)
Internal method for accessing MTJ's general transpose routine

Parameters:
destinationMatrix - matrix into which to store the result

getSubMatrixInto

protected void getSubMatrixInto(int minRow,
                                int maxRow,
                                int minColumn,
                                int maxColumn,
                                AbstractMTJMatrix destinationMatrix)
Internal routine for storing a submatrix into and AbstractMTJMatrix. 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
destinationMatrix - the destination submatrix of dimension (maxRow-minRow+1)x(maxColumn-minColumn+1)

timesInto

protected void timesInto(AbstractMTJMatrix multiplicationMatrix,
                         AbstractMTJMatrix destinationMatrix)
Internal function call that stores the result of a matrix multiply into the given destinationMatrix.

Parameters:
multiplicationMatrix - matrix to postmultiply this by
destinationMatrix - matrix to store the matrix multiplication result, must have rows == this.getNumRows and columns == multiplicationMatrix.getNumColumns

timesInto

protected void timesInto(AbstractMTJVector multiplicationVector,
                         AbstractMTJVector destinationVector)
Internal function call that stores the result of a matrix multiply into the given destinationVector.

Parameters:
multiplicationVector - vector to postmultiply this by
destinationVector - vector to store the matrix multiplication result, must have dimensionality == this.getNumRows

convertFromVector

public void convertFromVector(Vector parameters)
Description copied from interface: Matrix
uploads a matrix from a column-stacked vector of parameters, so that v(k) = A(i,j) = A( k%M, k/M )

Parameters:
parameters - column-stacked version of this

convertToVector

public DenseVector convertToVector()
Description copied from interface: Matrix
Creates a column-stacked version of this, so that v(k) = A(i,j) = v(j*M+i)

Returns:
column-stacked Vector representing this