Package ptolemy.data

Class FixMatrixToken

java.lang.Object

ptolemy.data.Token

ptolemy.data.MatrixToken

ptolemy.data.FixMatrixToken

public class FixMatrixToken
extends MatrixToken

A token that contains a 2-D FixToken matrix.

Since:

Ptolemy II 0.4

Version:

$Id$

Author:

Bart Kienhuis, Steve Neuendorffer

See Also:

FixPoint

Pt.AcceptedRating:

Yellow (kienhuis)

Pt.ProposedRating:

Yellow (neuendor)

Field Summary

Fields inherited from class ptolemy.data.MatrixToken

_nils, DO_COPY, DO_NOT_COPY

Fields inherited from class ptolemy.data.Token

NIL

Constructor Summary

Constructors

Constructor	Description
FixMatrixToken()	Construct a FixMatrixToken with a one by one matrix.
FixMatrixToken(java.lang.String init)	Construct a FixMatrixToken from the specified string.
FixMatrixToken(Token[] tokens, int rows, int columns)	Construct an FixMatrixToken from the specified array of tokens.
FixMatrixToken(FixPoint[][] value)	Construct a FixMatrixToken with the specified 2-D matrix.
FixMatrixToken(FixPoint[][] value, Precision precision)	Construct a FixMatrixToken with the specified 2-D matrix.

Method Summary

Modifier and Type	Method	Description
protected MatrixToken	_add(MatrixToken rightArgument)	Return a new token whose value is the value of the argument Token added to the value of this Token.
protected MatrixToken	_addElement(Token rightArgument)	Return a new token whose value is the value of the argument Token added from the value of each element of this Token.
protected MatrixToken	_multiply(MatrixToken rightArgument)	Return a new token whose value is the value of this token multiplied by the value of the argument token.
protected MatrixToken	_multiplyElement(Token rightArgument)	Return a new token whose value is the value of the argument Token multiplyed from the value of each element of this Token.
protected MatrixToken	_subtract(MatrixToken rightArgument)	Return a new token whose value is the value of the argument Token subtracted to the value of this Token.
protected MatrixToken	_subtractElement(Token rightArgument)	Return a new token whose value is the value of the argument Token subtracted from the value of each element of this Token.
protected MatrixToken	_subtractElementReverse(Token rightArgument)	Return a new token whose value is the value of the argument Token subtracted from the value of each element of this Token.
static FixMatrixToken	convert(Token token)	Convert the specified token into an instance of FixMatrixToken.
MatrixToken	crop(int rowStart, int colStart, int rowSpan, int colSpan)	Return a new matrix that is a sub-matrix of this matrix.
boolean	equals(java.lang.Object object)	Return true if the argument is an instance of FixMatrixToken of the same dimensions and the corresponding elements of the matrices are equal.
FixPoint[][]	fixMatrix()	Return the content of this token as a new 2-D FixPoint matrix.
int	getColumnCount()	Return the number of columns in the matrix.
Token	getElementAsToken(int row, int column)	Return the element of the matrix at the specified row and column in a FixToken.
FixPoint	getElementAt(int row, int column)	Return the element of the contained matrix at the specified row and column.
Type	getElementType()	Return the Type of the tokens contained in this matrix token.
int	getRowCount()	Return the number of rows in the matrix.
Type	getType()	Return the type of this token.
int	hashCode()	Return a hash code value for this token.
MatrixToken	join(MatrixToken[][] matrices)	Join a matrix of matrices into a single matrix by tiling.
Token	one()	Return a new Token representing the left multiplicative identity with the same precision as the current FixMatrixToken.
Token	oneRight()	Return a new Token representing the right multiplicative identity with the same precision as the current FixMatrixToken..
MatrixToken[][]	split(int[] rows, int[] columns)	Split this matrix into multiple matrices.
Token	zero()	Return a new Token representing the additive identity with the same precision as the current FixMatrixToken.

Methods inherited from class ptolemy.data.MatrixToken

_divideElement, _elementIsNil, _isCloseTo, _isEqualTo, _moduloElement, add, addReverse, arrayToMatrix, arrayToMatrix, arrayToMatrixReturnType, booleanMatrix, complexMatrix, create, createSequence, createSequenceReturnType, createTokenSequence, determineSequenceLength, divide, divideReverse, doubleMatrix, intMatrix, isCloseTo, isEqualTo, longMatrix, matrixToArray, matrixToArrayReturnType, modulo, moduloReverse, multiply, multiplyReverse, subtract, subtractReverse, toArray, toArrayColumnMajor, toArrayReturnType, toString

Methods inherited from class ptolemy.data.Token

isCloseTo, isNil, notSupportedConversionMessage, notSupportedIncomparableConversionMessage, notSupportedIncomparableMessage, notSupportedMessage, notSupportedNullNilStringMessage, pow, zeroReturnType

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

FixMatrixToken

public FixMatrixToken()

Construct a FixMatrixToken with a one by one matrix. The only element present in the matrix has value 0.0 and a precision of (32.0) which means 32 bits of which 0 bits are used for the fractional part.

FixMatrixToken

public FixMatrixToken(FixPoint[][] value)
               throws IllegalActionException

Construct a FixMatrixToken with the specified 2-D matrix. This method makes a copy of the matrix and stores the copy, so changes on the specified matrix after this token is constructed will not affect the content of this token. If any element of the specified matrix is null, then it is replaced with an element with value zero and precision the same as previous elements in the matrix. Note that the very first element cannot be null.

Parameters:

value - the 2D matrix of FixPoint values.

Throws:

IllegalActionException - If the precisions of the entries in the matrix are not all identical, or the specified matrix is null.

FixMatrixToken

public FixMatrixToken(java.lang.String init)
               throws IllegalActionException

Construct a FixMatrixToken from the specified string.

Parameters:

init - A string expression of a 2-D fix matrix.

Throws:

IllegalActionException - If the string does not contain a parsable 2-D fix matrix.

FixMatrixToken

public FixMatrixToken(FixPoint[][] value,
                      Precision precision)
               throws IllegalActionException

Construct a FixMatrixToken with the specified 2-D matrix. This method makes a copy of the matrix and stores the copy, so changes on the specified matrix after this token is constructed will not affect the content of this token. If any element of the specified matrix is null, then it is replaced with an element with value zero and precision the same as previous elements in the matrix. Note that the very first element cannot be null.

Parameters:

value - the 2D matrix of FixPoint values.

precision - The precision to use.

Throws:

IllegalActionException - If the precisions of the entries in the matrix are not all identical, or the specified matrix is null.

FixMatrixToken

public FixMatrixToken(Token[] tokens,
                      int rows,
                      int columns)
               throws IllegalActionException

Construct an FixMatrixToken from the specified array of tokens. The tokens in the array must be scalar tokens convertible into integers.

Parameters:

tokens - The array of tokens, which must contains rows*columns ScalarTokens.

rows - The number of rows in the matrix to be created.

columns - The number of columns in the matrix to be created.

Throws:

IllegalActionException - If the array of tokens is null, or the length of the array is not correct, or if one of the elements of the array is null, or if one of the elements of the array cannot be losslessly converted to a fixed point.

Method Detail

convert

public static FixMatrixToken convert(Token token)
                              throws IllegalActionException

Convert the specified token into an instance of FixMatrixToken. This method does lossless conversion. If the argument is already an instance of FixMatrixToken, it is returned without any change. Otherwise, if the argument is below FixMatrixToken in the type hierarchy, it is converted to an instance of FixMatrixToken or one of the subclasses of FixMatrixToken and returned. If none of the above condition is met, an exception is thrown.

Parameters:

token - The token to be converted to a FixMatrixToken.

Returns:

A FixMatrixToken

Throws:

IllegalActionException - If the conversion cannot be carried out.

crop

public MatrixToken crop(int rowStart,
                        int colStart,
                        int rowSpan,
                        int colSpan)
                 throws IllegalActionException

Return a new matrix that is a sub-matrix of this matrix.

Overrides:

crop in class MatrixToken

Parameters:

rowStart - The row to start on.

colStart - The column to start on.

rowSpan - The number of rows to copy.

colSpan - The number of columns to copy.

Returns:

a sub-matrix of this matrix.

Throws:

IllegalActionException - If the returned matrix is empty or if the specified parameters result in out of bounds accesses.

equals

public boolean equals(java.lang.Object object)

Return true if the argument is an instance of FixMatrixToken of the same dimensions and the corresponding elements of the matrices are equal.

Overrides:

equals in class java.lang.Object

Parameters:

object - An instance of Object.

Returns:

True if the argument is an instance of FixMatrixToken of the same dimensions and the corresponding elements of the matrices are equal.

fixMatrix

public FixPoint[][] fixMatrix()

Return the content of this token as a new 2-D FixPoint matrix.

Overrides:

fixMatrix in class MatrixToken

Returns:

A 2-D FixPoint matrix

getColumnCount

public int getColumnCount()

Return the number of columns in the matrix.

Specified by:

getColumnCount in class MatrixToken

Returns:

The number of columns in the matrix.

getElementAsToken

public Token getElementAsToken(int row,
                               int column)
                        throws java.lang.ArrayIndexOutOfBoundsException

Return the element of the matrix at the specified row and column in a FixToken.

Specified by:

getElementAsToken in class MatrixToken

Parameters:

row - The row index of the desired element.

column - The column index of the desired element.

Returns:

A FixToken containing the matrix element.

Throws:

java.lang.ArrayIndexOutOfBoundsException - If the specified row or column number is outside the range of the matrix.

getElementAt

public FixPoint getElementAt(int row,
                             int column)

Return the element of the contained matrix at the specified row and column.

Parameters:

row - The row index of the desired element.

column - The column index of the desired element.

Returns:

The FixPoint at the specified matrix entry.

Throws:

java.lang.ArrayIndexOutOfBoundsException - If the specified row or column number is outside the range of the matrix.

getElementType

public Type getElementType()

Return the Type of the tokens contained in this matrix token. This must be a type representing a scalar token.

Specified by:

getElementType in class MatrixToken

Returns:

BaseType.UNSIZED_FIX.

getRowCount

public int getRowCount()

Return the number of rows in the matrix.

Specified by:

getRowCount in class MatrixToken

Returns:

The number of rows in the matrix.

getType

public Type getType()

Return the type of this token.

Overrides:

getType in class Token

Returns:

BaseType.FIX_MATRIX

hashCode

public int hashCode()

Return a hash code value for this token. This method returns the integer portion of the sum of the elements.

Overrides:

hashCode in class java.lang.Object

Returns:

A hash code value for this token.

join

public MatrixToken join(MatrixToken[][] matrices)
                 throws IllegalActionException

Join a matrix of matrices into a single matrix by tiling. All matrices in the matrix must be of the same type, the same type as this matrix. But none of them needs to actually be this matrix. This base class simply throws an exception. Derived classes provide the implementation. The number of columns in the resulting matrix is the sum of the number of columns in the first row of the argument. The number of rows in the resulting matrix is the sum of the number of rows in the first column of the argument. The matrices are copied into the result starting at the position determined by the first row or column. If the matrices overlap, then while copying left to right, top-to-bottom, data will be overwritten. If there are gaps, the resulting matrix will be filled with zeros.

Overrides:

join in class MatrixToken

Parameters:

matrices - A two-dimensional array of matrix tokens.

Returns:

A new matrix token of the same type as the elements in the input matrix of matrix tokens.

Throws:

IllegalActionException - If the types of the matrices in the input are not all the same, or if tiling fails due to size incompatibilities, or if the input matrix has no tokens.

split

public MatrixToken[][] split(int[] rows,
                             int[] columns)

Split this matrix into multiple matrices. See the base class for documentation.

Overrides:

split in class MatrixToken

Parameters:

rows - The number of rows per submatrix.

columns - The number of columns per submatrix.

Returns:

An array of matrix tokens.

one

public Token one()

Return a new Token representing the left multiplicative identity with the same precision as the current FixMatrixToken. The returned token contains an identity matrix whose dimensions are the same as the number of rows of the matrix contained in this token.

Overrides:

one in class Token

Returns:

A new FixMatrixToken containing the left multiplicative identity.

oneRight

public Token oneRight()

Return a new Token representing the right multiplicative identity with the same precision as the current FixMatrixToken.. The returned token contains an identity matrix whose dimensions are the same as the number of columns of the matrix contained in this token.

Overrides:

oneRight in class MatrixToken

Returns:

A new FixMatrixToken containing the right multiplicative identity.

zero

public Token zero()

Return a new Token representing the additive identity with the same precision as the current FixMatrixToken. The returned token contains a matrix whose elements are all zero, and the size of the matrix is the same as the matrix contained in this token.

Overrides:

zero in class Token

Returns:

A new FixMatrixToken containing the additive identity.

_add

protected MatrixToken _add(MatrixToken rightArgument)
                    throws IllegalActionException

Return a new token whose value is the value of the argument Token added to the value of this Token. It is assumed that the type of the argument is FixMatrixToken.

Overrides:

_add in class MatrixToken

Parameters:

rightArgument - The token to add to this token.

Returns:

A new FixMatrixToken containing the result.

Throws:

IllegalActionException - If the units are not compatible, or this operation is not supported by the derived class.

_addElement

protected MatrixToken _addElement(Token rightArgument)
                           throws IllegalActionException

Return a new token whose value is the value of the argument Token added from the value of each element of this Token. It is assumed that the type of the argument is the same as the type of each element of this class or is a matrix with one element.

Overrides:

_addElement in class MatrixToken

Parameters:

rightArgument - The token to add from this token.

Returns:

A new Token containing the result.

Throws:

IllegalActionException - If this operation is not supported by the derived class.

_multiply

protected MatrixToken _multiply(MatrixToken rightArgument)
                         throws IllegalActionException

Return a new token whose value is the value of this token multiplied by the value of the argument token. It is assumed that the type of the argument is FixMatrixToken.

Overrides:

_multiply in class MatrixToken

Parameters:

rightArgument - The token to multiply this token by.

Returns:

A new FixMatrixToken containing the result.

Throws:

IllegalActionException - If the units are not compatible, or if the matrix dimensions are incompatible.

_multiplyElement

protected MatrixToken _multiplyElement(Token rightArgument)
                                throws IllegalActionException

Return a new token whose value is the value of the argument Token multiplyed from the value of each element of this Token. It is assumed that the type of the argument is the same as the type of each element of this class or is a matrix with one element.

Overrides:

_multiplyElement in class MatrixToken

Parameters:

rightArgument - The token to multiply from this token.

Returns:

A new Token containing the result.

Throws:

IllegalActionException - If this operation is not supported by the derived class.

_subtract

protected MatrixToken _subtract(MatrixToken rightArgument)
                         throws IllegalActionException

Return a new token whose value is the value of the argument Token subtracted to the value of this Token. It is assumed that the type of the argument is FixMatrixToken.

Overrides:

_subtract in class MatrixToken

Parameters:

rightArgument - The token to subtract to this token.

Returns:

A new FixMatrixToken containing the result.

Throws:

IllegalActionException - If the units are not compatible, or this operation is not supported by the derived class.

_subtractElement

protected MatrixToken _subtractElement(Token rightArgument)
                                throws IllegalActionException

Return a new token whose value is the value of the argument Token subtracted from the value of each element of this Token. It is assumed that the type of the argument is the same as the type of each element of this class or is a matrix with one element.

Overrides:

_subtractElement in class MatrixToken

Parameters:

rightArgument - The token to subtract from this token.

Returns:

A new Token containing the result.

Throws:

IllegalActionException - If this operation is not supported by the derived class.

_subtractElementReverse

protected MatrixToken _subtractElementReverse(Token rightArgument)
                                       throws IllegalActionException

Return a new token whose value is the value of the argument Token subtracted from the value of each element of this Token. It is assumed that the type of the argument is the same as the type of each element of this class or is a matrix with one element.

Overrides:

_subtractElementReverse in class MatrixToken

Parameters:

rightArgument - The token to subtract from this token.

Returns:

A new Token containing the result.

Throws:

IllegalActionException - If this operation is not supported by the derived class.