maspack.matrix
Class MatrixObject

java.lang.Object
  maspack.matrix.MatrixObject

Direct Known Subclasses:

AffineTransform2dObject, AffineTransform3dObject, Matrix2dObject, Matrix3dObject, Matrix4dObject, MatrixNd, SpatialInertia

public abstract class MatrixObject

extends java.lang.Object

Base class for matrices. It provides methods which allow one to set and get various components of a matrix (individual elements, rows, columns, submatrics), and to do various non-modifying queries such as finding out its size, computing it's determinant, or comparing it with other matrices. There are also methods for producing a string representation of the matrix and for reading its contents from a tokenizer. There is an abstract method setSize for resizing, which can be used unless the matrix size is fixed (which can be determined using isFixedSize).

This base class does not publicly support matrix operations such as multiplication or addition. The reason for that is that subclasses may implement matrices with a specific structure, which could then be compromised by arbitrary operations. For instance, if a subclass of MatrixObject implements orthogonal matrices, then it would not make sense for that class to allow an add operation. Similarly, if a subclass implemented symmetric matrices, then any multiplication methods supported by that class should not be open to general matrices.

Of course, it is possible to corrupt any special subclass structure using the set methods provided in this base class, but it was felt that not including such routines would be overly restrictive. It is therefore up to the user to safeguard subclass integrity when using them.

Note that indices for matrix elements, rows, and columns are zero-based. The range of valid indices for a matrix of size m X n is [0, ... , m-1] and code>[0, ... , n-1].

Constructor Summary

MatrixObject()

Method Summary

abstract int	colSize() Returns the number of columns in this matrix.
double	determinant() Returns the determinant of this matrix, which must be square
boolean	epsilonEquals(MatrixObject M1, double epsilon) Returns true if the elements of this matrix equal those of matrix M1within a prescribed tolerance epsilon.
boolean	equals(MatrixObject M1) Returns true if the elements of this matrix exactly equal those of matrix M1.
boolean	equals(java.lang.Object obj) Returns true if this matrix and a specified object have the same class type and if all the elements are exactly equal.
double	frobeniusNorm() Returns the Frobenius norm of this matrix.
void	get(double[] values) Copies the elements of this matrix into an array of doubles.
void	get(double[][] values) Copies the elements of this matrix into a 2-dimensional array of doubles.
abstract double	get(int i, int j) Gets a single element of this matrix.
void	getColumn(int j, double[] values) Copies a column of this matrix into an array of doubles.
void	getColumn(int j, VectorObject v) Copies a column of this matrix into a VectorObject.
void	getRow(int i, double[] values) Copies a row of this matrix into an array of doubles.
void	getRow(int i, VectorObject v) Copies a row of this matrix into a VectorObject.
double	infinityNorm() Returns the infinity norm of this matrix.
boolean	isFixedSize() Returns true if this matrix is of fixed size.
double	oneNorm() Returns the 1 norm of this matrix.
abstract int	rowSize() Returns the number of rows in this matrix.
void	scan(java.io.StreamTokenizer stok) Sets the contents of this matrix to values read from a StreamTokenizer.
void	set(double[] values) Sets the elements of this matrix from an array of doubles.
void	set(double[][] values) Sets the elements of this matrix from a 2-dimensional array of doubles.
abstract void	set(int i, int j, double value) Sets a single element of this matrix.
void	set(MatrixObject M) Sets the size and values of this matrix to those of another matrix.
void	setColumn(int j, double[] values) Sets a column of this matrix from an array of doubles.
void	setColumn(int j, VectorObject v) Sets a column of this matrix from a VectorObject.
void	setRow(int i, double[] values) Set a row of this matrix from an array of doubles.
void	setRow(int i, VectorObject v) Sets a row of this matrix from a VectorObject.
void	setSize(int numRows, int numCols) Sets the size of this matrix.
java.lang.String	toString() Returns a String representation of this matrix, using the default format "%g" (see toString(String).
java.lang.String	toString(NumberFormat fmt) Returns a String representation of this matrix, in which each element is formated using a C printf style as decribed by the parameter NumberFormat.
java.lang.String	toString(java.lang.String fmtStr) Returns a String representation of this matrix, in which each element is formated using a C printf style format string.

Methods inherited from class java.lang.Object

getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

MatrixObject

public MatrixObject()

Method Detail

rowSize

public abstract int rowSize()

Returns the number of rows in this matrix.

Returns:

number of rows

colSize

public abstract int colSize()

Returns the number of columns in this matrix.

Returns:

number of columns

get

public abstract double get(int i,
                           int j)

Gets a single element of this matrix.

Parameters:

i - element row index

j - element column index

Returns:

element value

get

public void get(double[] values)

Copies the elements of this matrix into an array of doubles. The elements are stored using row-major order, so that element (i,j) is stored at location i*colSize()+j.

Parameters:

values - array into which values are copied

get

public void get(double[][] values)

Copies the elements of this matrix into a 2-dimensional array of doubles.

Parameters:

values - array into which values are copied

Throws:

java.lang.IllegalArgumentException - values has inconsistent row sizes

ImproperSizeException - dimensions of values do not match the size of this matrix

getColumn

public void getColumn(int j,
                      double[] values)

Copies a column of this matrix into an array of doubles.

Parameters:

j - column index

values - array into which the column is copied

getRow

public void getRow(int i,
                   double[] values)

Copies a row of this matrix into an array of doubles.

Parameters:

i - row index

values - array into which the row is copied

getColumn

public void getColumn(int j,
                      VectorObject v)

Copies a column of this matrix into a VectorObject.

Parameters:

j - column index

v - vector into which the column is copied

Throws:

ImproperSizeException - vector's size not equal to the number of matrix rows and the vector cannot be resized

getRow

public void getRow(int i,
                   VectorObject v)

Copies a row of this matrix into a VectorObject.

Parameters:

i - row index

v - vector into which the row is copied

Throws:

ImproperSizeException - vector's size not equal to the number of matrix columns and the vector cannot be resized

set

public abstract void set(int i,
                         int j,
                         double value)

Sets a single element of this matrix.

Parameters:

i - element row index

j - element column index

value - element value

set

public void set(double[] values)

Sets the elements of this matrix from an array of doubles. The elements in the array should be stored using row-major order, so that element (i,j) is stored at location i*colSize()+j.

Parameters:

values - array from which values are copied

set

public void set(double[][] values)

Sets the elements of this matrix from a 2-dimensional array of doubles.

Parameters:

values - array from which values are copied

Throws:

java.lang.IllegalArgumentException - values has inconsistent row sizes

ImproperSizeException - dimensions of values do not match the size of this matrix

set

public void set(MatrixObject M)

Sets the size and values of this matrix to those of another matrix.

Parameters:

M - matrix whose size and values are copied

Throws:

ImproperSizeException - matrices have different sizes and this matrix cannot be resized accordingly

setColumn

public void setColumn(int j,
                      double[] values)

Sets a column of this matrix from an array of doubles.

Parameters:

j - column index

values - array from which column values are copied

setRow

public void setRow(int i,
                   double[] values)

Set a row of this matrix from an array of doubles.

Parameters:

i - row index

values - array from which the row is copied

setColumn

public void setColumn(int j,
                      VectorObject v)

Sets a column of this matrix from a VectorObject.

Parameters:

j - column index

v - vector from which the column is copied

Throws:

ImproperSizeException - vector's size not equal to the number of matrix rows

setRow

public void setRow(int i,
                   VectorObject v)

Sets a row of this matrix from a VectorObject.

Parameters:

i - row index

v - vector from which the row is copied

Throws:

ImproperSizeException - vector's size not equal to the number of matrix columns

isFixedSize

public boolean isFixedSize()

Returns true if this matrix is of fixed size. If this matrix is not of fixed size, then it can be resized dynamically, either explicitly using setSize, or implicitly when used as a result for various matrix operations.

Returns:

true if this matrix is of fixed size

See Also:

setSize(int, int)

setSize

public void setSize(int numRows,
                    int numCols)

Sets the size of this matrix. This operation is only supported if isFixedSize returns false.

Parameters:

numRows - new row size

numCols - new column size

Throws:

java.lang.UnsupportedOperationException - if this operation is not supported

See Also:

isFixedSize()

determinant

public double determinant()
                   throws ImproperSizeException

Returns the determinant of this matrix, which must be square

Returns:

matrix determinant

Throws:

ImproperSizeException - if the matrix is not square

epsilonEquals

public boolean epsilonEquals(MatrixObject M1,
                             double epsilon)
                      throws ImproperSizeException

Returns true if the elements of this matrix equal those of matrix M1within a prescribed tolerance epsilon.

Parameters:

M1 - matrix to compare with

epsilon - comparison tolerance

Returns:

false if the matrices are not equal within the specified tolerance, or have different sizes

Throws:

ImproperSizeException

equals

public boolean equals(MatrixObject M1)
               throws ImproperSizeException

Returns true if the elements of this matrix exactly equal those of matrix M1.

Parameters:

M1 - matrix to compare with

Returns:

false if the matrices are not equal or have different sizes

Throws:

ImproperSizeException

equals

public boolean equals(java.lang.Object obj)

Returns true if this matrix and a specified object have the same class type and if all the elements are exactly equal.

Parameters:

obj - object to compare with

Returns:

false if the objects are not equal

oneNorm

public double oneNorm()

Returns the 1 norm of this matrix. This is equal to the maximum of the vector 1-norm of each column.

Returns:

1 norm of this matrix

infinityNorm

public double infinityNorm()

Returns the infinity norm of this matrix. This is equal to the maximum of the vector 1-norm of each row.

Returns:

infinity norm of this matrix

frobeniusNorm

public double frobeniusNorm()

Returns the Frobenius norm of this matrix. This is equal to the square root of the sum of the squares of each element.

Returns:

Frobenius norm of this matrix

toString

public java.lang.String toString()

Returns a String representation of this matrix, using the default format "%g" (see toString(String).

Returns:

String representation of this matrix

toString

public java.lang.String toString(java.lang.String fmtStr)

Returns a String representation of this matrix, in which each element is formated using a C printf style format string. A new line is inserted between each row. For a description of the format string syntax, see NumberFormat.

Parameters:

fmtStr - numeric format specification

Returns:

String representation of this matrix

toString

public java.lang.String toString(NumberFormat fmt)

Returns a String representation of this matrix, in which each element is formated using a C printf style as decribed by the parameter NumberFormat. When called numerous times, this routine can be more efficient than toString(String), because the NumberFormat does not need to be recreated each time from a specification string.

Parameters:

fmt - numeric format

Returns:

String representation of this matrix

scan

public void scan(java.io.StreamTokenizer stok)
          throws java.io.IOException

Sets the contents of this matrix to values read from a StreamTokenizer. The matrix elements should be arranged in row-major order, separated by white space, with rows separated by either a semicolons or a newline. The entire set of elements should be surrounded by square brackets. For example,

 [ 1.2  4   5
   6    3.1 0 ]
 

defines a 2 x 3 matrix.

If the matrix is not of fixed-size, it will be resized to fit the input. The StreamTokenizer will be set by this method to parse numbers, and it should already be configured to recognize the characters '+', -, and ';' as tokens.

Note:This method disables numeric parsing in the StreamTokenizer. This is because the method does its own numeric parsing, in order to handle exponents.

Parameters:

stok - Tokenizer from which matrix values are read

Throws:

ImproperSizeException - if this matrix has a fixed size which is incompatible with the input, or if the sizes of the specified rows are inconsistent

java.io.IOException