java.lang.Object
- ptolemy.data.Token
- - ptolemy.data.MatrixToken

Direct Known Subclasses:

BooleanMatrixToken, ComplexMatrixToken, ConcreteMatrixToken, DoubleMatrixToken, FixMatrixToken, IntMatrixToken, LongMatrixToken
```
public abstract class MatrixToken
extends Token
```
Abstract base class for tokens that contain a 2-D matrix. This class defines methods for type conversion among different matrix tokens. The implementation in this base class just throws an exception. Derived classes should override those methods where the corresponding conversion can be achieved without loss of information. Derived classes should call _elementIsNil() when they encounter a nil token during construction.

Since:

Ptolemy II 0.2

Version:

$Id$

Author:

Yuhong Xiong, Steve Neuendorffer, contributor: Christopher Brooks

Pt.AcceptedRating:

Red (cxh) nil token code

Pt.ProposedRating:

Yellow (cxh)

Field Summary

Fields
Modifier and Type	Field	Description
`protected java.util.Set`	`_nils`	HashSet of nil elements, where each element is the index of the element in _value[] that should be nil.
`static int`	`DO_COPY`	A constant indicating to constructors that contents of an argument 2-D matrix should be copied.
`static int`	`DO_NOT_COPY`	A constant indicating to constructors not to copy the contents of an argument 2-D matrix, but instead to just copy the pointer to the matrix.

Fields inherited from class ptolemy.data.Token
NIL

Constructor Summary

Constructors
Constructor Description

MatrixToken()

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Concrete Methods Deprecated Methods
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 to the value of each element of this Token.
`protected MatrixToken`	`_divideElement(Token rightArgument)`	Return a new token whose elements are the result of dividing the elements of this token by the argument.
`protected void`	`_elementIsNil(int element)`	Add the element to the _nils Set.
`protected BooleanToken`	`_isCloseTo(MatrixToken token, double distance)`	Test whether the value of this token is close to the first argument, where "close" means that the distance between their elements is less than or equal to the second argument.
`protected BooleanToken`	`_isEqualTo(MatrixToken rightArgument)`	Test for equality of the values of this Token and the argument Token.
`protected MatrixToken`	`_moduloElement(Token rightArgument)`	Return a new token whose elements are the modulo of the elements of this token by the argument.
`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 this token multiplied by the value of the argument scalar token.
`protected MatrixToken`	`_subtract(MatrixToken rightArgument)`	Return a new token whose value is the value of the argument token subtracted from 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 each element of this Token subtracted from the value the argument Token.
`Token`	`add(Token rightArgument)`	Return a new token whose value is the sum of this token and the argument.
`Token`	`addReverse(Token leftArgument)`	Return a new token whose value is the sum of this token and the argument.
`static MatrixToken`	`arrayToMatrix(Token[] tokens, int rows, int columns)`	Create a new instance of a MatrixToken subclass with the given number of rows and columns.
`static MatrixToken`	`arrayToMatrix(Type type, Token[] tokens, int rows, int columns)`	Create a new instance of a MatrixToken subclass with the given element type and number of rows and columns.
`static Type`	`arrayToMatrixReturnType(Type type1, Type type2, Type type3)`	Return the (exact) return type of the arrayToMatrix function above.
`boolean[][]`	`booleanMatrix()`	Return the content of this token as a 2-D boolean matrix.
`Complex[][]`	`complexMatrix()`	Return a copy of the content of this token as a 2-D Complex matrix.
`static MatrixToken`	`create(Token[] tokens, int rows, int columns)`	Deprecated. Use arrayToMatrix() instead.
`static Token[]`	`createSequence(Token start, Token increment, int length)`	Create an array of tokens of the given length.
`static Type`	`createSequenceReturnType(Type type1, Type type2, Type type3)`	Return the (exact) return type of the createSequence function above.
`static Token[]`	`createTokenSequence(Token start, Token increment, int length)`	Deprecated. Use createSequence() instead.
`MatrixToken`	`crop(int rowStart, int colStart, int rowSpan, int colSpan)`	Return a new matrix that is a sub-matrix of this matrix.
`static int`	`determineSequenceLength(ScalarToken start, ScalarToken increment, ScalarToken end)`	Count the number of tokens differing by the given increment that fit in a range between the given start token and the given end token.
`Token`	`divide(Token rightArgument)`	Return a new token whose value is the value of this token divided by the value of the argument token.
`Token`	`divideReverse(Token leftArgument)`	Return a new token whose value is the value of the argument token divided by the value of this token.
`double[][]`	`doubleMatrix()`	Return the content of this token as a 2-D double matrix.
`FixPoint[][]`	`fixMatrix()`	Return the content of this token as a 2-D fixed point matrix.
`abstract int`	`getColumnCount()`	Return the number of columns of the matrix.
`abstract Token`	`getElementAsToken(int row, int column)`	Return the element of the matrix at the specified row and column wrapped in a token.
`abstract Type`	`getElementType()`	Return the Type of the tokens contained in this matrix token.
`abstract int`	`getRowCount()`	Return the number of rows of the matrix.
`int[][]`	`intMatrix()`	Return the content of this token as a 2-D integer matrix.
`BooleanToken`	`isCloseTo(Token rightArgument, double epsilon)`	Test whether the value of this Token is close to the argument Token.
`BooleanToken`	`isEqualTo(Token rightArgument)`	Test for equality of the values of this Token and the argument Token.
`MatrixToken`	`join(MatrixToken[][] matrices)`	Join a matrix of matrices into a single matrix by tiling.
`long[][]`	`longMatrix()`	Return the content of this matrix as a 2-D long matrix.
`static ArrayToken`	`matrixToArray(MatrixToken matrix)`	Create a new instance of ArrayToken that contains the values in the specified matrix.
`static Type`	`matrixToArrayReturnType(Type type)`	Return the (exact) return type of the toArray function above.
`Token`	`modulo(Token rightArgument)`	Return a new token whose value is this token modulo the value of the argument token.
`Token`	`moduloReverse(Token leftArgument)`	Return a new token whose value is the value of the argument token modulo the value of this token.
`Token`	`multiply(Token rightArgument)`	Return a new token whose value is the value of this token multiplied by the value of the argument token.
`Token`	`multiplyReverse(Token leftArgument)`	Return a new token whose value is the value of the argument token multiplied by the value of this token.
`Token`	`oneRight()`	Return a new Token representing the right multiplicative identity.
`MatrixToken[][]`	`split(int[] rows, int[] columns)`	Split this matrix into multiple matrices.
`Token`	`subtract(Token rightArgument)`	Return a new token whose value is the value of the argument token subtracted from the value of this token.
`Token`	`subtractReverse(Token leftArgument)`	Return a new token whose value is the value of this token subtracted from the value of the argument token.
`ArrayToken`	`toArray()`	Return an ArrayToken containing the all the values of this matrix token.
`ArrayToken`	`toArrayColumnMajor()`	Return an ArrayToken containing the all the values of this matrix token.
`static Type`	`toArrayReturnType(Type type)`	Return the (exact) return type of the toArray function above.
`java.lang.String`	`toString()`	Return the value of this token as a string that can be parsed by the expression language to recover a token with the same value.

Methods inherited from class ptolemy.data.Token
getType, isCloseTo, isNil, notSupportedConversionMessage, notSupportedIncomparableConversionMessage, notSupportedIncomparableMessage, notSupportedMessage, notSupportedNullNilStringMessage, one, pow, zero, zeroReturnType

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - DO_COPY
```
public static final int DO_COPY
```
    A constant indicating to constructors that contents of an argument 2-D matrix should be copied. The contents of the input 2-D matrix may be modified after construction without violating the immutability of MatrixTokens.
    
    See Also:
    
    Constant Field Values
  - DO_NOT_COPY
```
public static final int DO_NOT_COPY
```
    A constant indicating to constructors not to copy the contents of an argument 2-D matrix, but instead to just copy the pointer to the matrix. The contents of the input 2-D matrix should NOT be modified after construction of an instance of MatrixToken, if the property of immutability is to be preserved.
    
    See Also:
    
    Constant Field Values
  - _nils
```
protected java.util.Set _nils
```
    HashSet of nil elements, where each element is the index of the element in _value[] that should be nil.
- Constructor Detail
  - MatrixToken
```
public MatrixToken()
```
- Method Detail
  - add
```
public Token add(Token rightArgument)
          throws IllegalActionException
```
    Return a new token whose value is the sum of this token and the argument. Type conversion also occurs here, so that the operation is performed at the least type necessary to ensure precision. The returned type is the same as the type chosen for the operation. Generally, this is higher of the type of this token and the argument type. Subclasses should not generally override this method, but override the protected _add() method to ensure that type conversion is performed consistently.
    
    Overrides:
    
    add in class Token
    
    Parameters:
    
    rightArgument - The token to add to this token.
    
    Returns:
    
    A new token containing the result.
    
    Throws:
    
    IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.
  - addReverse
```
public Token addReverse(Token leftArgument)
                 throws IllegalActionException
```
    Return a new token whose value is the sum of this token and the argument. Type resolution also occurs here, with the returned token type chosen to achieve a lossless conversion.
    
    Overrides:
    
    addReverse in class Token
    
    Parameters:
    
    leftArgument - The token to add this token to.
    
    Returns:
    
    A new token containing the result.
    
    Throws:
    
    IllegalActionException - If the argument token is not of a type that can be added to this token, or the units of this token and the argument token are not the same.
  - arrayToMatrix
```
public static MatrixToken arrayToMatrix(Token[] tokens,
                                        int rows,
                                        int columns)
                                 throws IllegalActionException
```
    Create a new instance of a MatrixToken subclass with the given number of rows and columns. The token will contain all of the elements of the given array. The element type of the matrix token will be the least upper bound of the types of all of the tokens in the given array. The size of the array must be (rows*columns).
    
    Parameters:
    
    tokens - an array of Token objects
    
    rows - The number of rows.
    
    columns - The number of columns.
    
    Returns:
    
    An instance of a subclass of MatrixToken.
    
    Throws:
    
    IllegalActionException - If no type exists for the matrix token, or the array of tokens is not the right size, or the array is null.
  - arrayToMatrix
```
public static MatrixToken arrayToMatrix(Type type,
                                        Token[] tokens,
                                        int rows,
                                        int columns)
                                 throws IllegalActionException
```
    Create a new instance of a MatrixToken subclass with the given element type and number of rows and columns. The token will contain all of the elements of the given array. The size of the array must be (rows*columns).
    
    Parameters:
    
    type - The type of the MatrixToken.
    
    tokens - an array of Token objects
    
    rows - The number of rows.
    
    columns - The number of columns.
    
    Returns:
    
    An instance of a subclass of MatrixToken.
    
    Throws:
    
    IllegalActionException - If the type is not possible, or the array of tokens is not the right size, or the array is null.
  - arrayToMatrixReturnType
```
public static Type arrayToMatrixReturnType(Type type1,
                                           Type type2,
                                           Type type3)
                                    throws IllegalActionException
```
    Return the (exact) return type of the arrayToMatrix function above. If the first argument type is an array type, then return a matrix type of the same element type, otherwise return BaseType.UNKNOWN.
    
    Parameters:
    
    type1 - The type of the first argument to the corresponding function.
    
    type2 - The type of the second argument to the corresponding function.
    
    type3 - The type of the third argument to the corresponding function.
    
    Returns:
    
    The type of the value returned from the corresponding function.
    
    Throws:
    
    IllegalActionException - If thrown while getting the matrix type for type1.
  - booleanMatrix
```
public boolean[][] booleanMatrix()
                          throws IllegalActionException
```
    Return the content of this token as a 2-D boolean matrix. In this base class, just throw an exception.
    
    Returns:
    
    A 2-D boolean matrix.
    
    Throws:
    
    IllegalActionException - If the token cannot be represented as requested (always thrown in this base class).
  - complexMatrix
```
public Complex[][] complexMatrix()
                          throws IllegalActionException
```
    Return a copy of the content of this token as a 2-D Complex matrix. In this base class, just throw an exception.
    
    Returns:
    
    A 2-D Complex matrix.
    
    Throws:
    
    IllegalActionException - If the token cannot be represented as requested (always thrown in this base class).
  - create
```
@Deprecated
public static MatrixToken create(Token[] tokens,
                                 int rows,
                                 int columns)
                          throws IllegalActionException
```
    Deprecated.
    Use arrayToMatrix() instead.
    
    Create a new instance of a MatrixToken subclass with the given number of rows and columns. The token will contain all of the elements of the given array. The element type of the matrix token will be the least upper bound of the types of all of the tokens in the given array. The size of the array must be (rows*columns).
    
    Parameters:
    
    tokens - an array of Token objects.
    
    rows - The number of rows.
    
    columns - The number of columns.
    
    Returns:
    
    An instance of a subclass of MatrixToken.
    
    Throws:
    
    IllegalActionException - If no type exists for the matrix token, or the array of tokens is not the right size, or the array is null.
  - createSequence
```
public static Token[] createSequence(Token start,
                                     Token increment,
                                     int length)
                              throws IllegalActionException
```
    Create an array of tokens of the given length. The first token in the sequence will have value start and each succeeding token will have the value created by adding the given increment to the preceding token.
    
    Parameters:
    
    start - The value of the first element of the returned array.
    
    increment - The difference between elements in the array.
    
    length - The size of the array to create, which must not be negative.
    
    Returns:
    
    An array of tokens of the given length.
    
    Throws:
    
    IllegalActionException - If the length is negative, or tokens of the given type cannot be added together.
  - createSequenceReturnType
```
public static Type createSequenceReturnType(Type type1,
                                            Type type2,
                                            Type type3)
                                     throws IllegalActionException
```
    Return the (exact) return type of the createSequence function above. The return type is an array type whose element type is the least upper bound of the first two types.
    
    Parameters:
    
    type1 - The type of the first argument to the corresponding function.
    
    type2 - The type of the second argument to the corresponding function.
    
    type3 - The type of the third argument to the corresponding function.
    
    Returns:
    
    The type of the value returned from the corresponding function.
    
    Throws:
    
    IllegalActionException - If thrown while creating a new ArrayType object.
  - createTokenSequence
```
@Deprecated
public static Token[] createTokenSequence(Token start,
                                          Token increment,
                                          int length)
                                   throws IllegalActionException
```
    Deprecated.
    Use createSequence() instead.
    
    Create an array of tokens of the given length. The first token in the sequence will have value start and each succeeding token will have the value created by adding the given increment to the preceding token.
    
    Parameters:
    
    start - The value of the first element of the returned array.
    
    increment - The difference between elements in the array.
    
    length - The size of the array to create, which must not be negative.
    
    Returns:
    
    an array of tokens.
    
    Throws:
    
    IllegalActionException - If the length is negative, or tokens of the given type cannot be added together.
  - 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.
    
    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:
    
    subclasses return a sub-matrix of this matrix. This base class does not return, it always throws an exception.
    
    Throws:
    
    IllegalActionException - If the operation is not supported. Always thrown in this base class.
  - determineSequenceLength
```
public static int determineSequenceLength(ScalarToken start,
                                          ScalarToken increment,
                                          ScalarToken end)
                                   throws IllegalActionException
```
    Count the number of tokens differing by the given increment that fit in a range between the given start token and the given end token. This computes, type polymorphically, the value floor(((end-start)/increment) + 1). If the size of the sequence cannot be determined, because the increment is zero, or the increment is positive and end is greater than start, or the increment is negative and start is greater than end, then an exception will be thrown.
    
    Parameters:
    
    start - The given start token.
    
    increment - The increment.
    
    end - The given end token
    
    Returns:
    
    The size of the sequence, which will be greater than zero.
    
    Throws:
    
    IllegalActionException - If the length of the sequence cannot be determined, or the tokens provided do not support the zero, isEqualTo, isLessThan, add, divide, or subtract operations, or is not convertible to a double token.
  - divide
```
public final Token divide(Token rightArgument)
                   throws IllegalActionException
```
    Return a new token whose value is the value of this token divided by the value of the argument token. Division is not supported for matrices, so this throws an exception if the argument is a matrix. However, if it is a scalar, then division is performed elementwise.
    
    Overrides:
    
    divide in class Token
    
    Parameters:
    
    rightArgument - The token that divides this token.
    
    Returns:
    
    A new token containing the result.
    
    Throws:
    
    IllegalActionException - If the operation does not make sense for the given types.
  - divideReverse
```
public Token divideReverse(Token leftArgument)
                    throws IllegalActionException
```
    Return a new token whose value is the value of the argument token divided by the value of this token. Division is not supported for matrices, so this always throws an exception.
    
    Overrides:
    
    divideReverse in class Token
    
    Parameters:
    
    leftArgument - The token to be divided by the value of this token.
    
    Returns:
    
    A new token containing the result.
    
    Throws:
    
    IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.
  - doubleMatrix
```
public double[][] doubleMatrix()
                        throws IllegalActionException
```
    Return the content of this token as a 2-D double matrix. In this base class, just throw an exception.
    
    Returns:
    
    A 2-D double matrix.
    
    Throws:
    
    IllegalActionException - If the token cannot be represented as requested (always thrown in this base class).
  - fixMatrix
```
public FixPoint[][] fixMatrix()
                       throws IllegalActionException
```
    Return the content of this token as a 2-D fixed point matrix. In this base class, just throw an exception.
    
    Returns:
    
    A 2-D fix matrix.
    
    Throws:
    
    IllegalActionException - If the token cannot be represented as requested (always thrown in this base class).
  - getColumnCount
```
public abstract int getColumnCount()
```
    Return the number of columns of the matrix.
    
    Returns:
    
    The number of columns of the matrix.
  - getElementAsToken
```
public abstract Token getElementAsToken(int row,
                                        int column)
                                 throws java.lang.ArrayIndexOutOfBoundsException
```
    Return the element of the matrix at the specified row and column wrapped in a token.
    
    Parameters:
    
    row - The row index of the desired element.
    
    column - The column index of the desired element.
    
    Returns:
    
    A token containing the matrix element.
    
    Throws:
    
    java.lang.ArrayIndexOutOfBoundsException - If the specified row or column number is outside the range of the matrix.
  - getElementType
```
public abstract Type getElementType()
```
    Return the Type of the tokens contained in this matrix token.
    
    Returns:
    
    A Type.
  - getRowCount
```
public abstract int getRowCount()
```
    Return the number of rows of the matrix.
    
    Returns:
    
    The number of rows of the matrix.
  - intMatrix
```
public int[][] intMatrix()
                  throws IllegalActionException
```
    Return the content of this token as a 2-D integer matrix. In this base class, just throw an exception.
    
    Returns:
    
    A 2-D integer matrix.
    
    Throws:
    
    IllegalActionException - If the token cannot be represented as requested (always thrown in this base class).
  - isCloseTo
```
public final BooleanToken isCloseTo(Token rightArgument,
                                    double epsilon)
                             throws IllegalActionException
```
    Test whether the value of this Token is close to the argument Token. In this base class, we call isEqualTo() and the epsilon argument is ignored. This method should be overridden in derived classes such as DoubleToken and ComplexToken to provide type specific actions for equality testing using the epsilon argument
    
    Overrides:
    
    isCloseTo in class Token
    
    Parameters:
    
    rightArgument - The token to test closeness of this token with.
    
    epsilon - The value that we use to determine whether two tokens are close. In this base class, the epsilon argument is ignored.
    
    Returns:
    
    a boolean token that contains the value true if the value and units of this token are close to those of the argument token.
    
    Throws:
    
    IllegalActionException - If the argument token is not of a type that can be compared with this token.
    
    See Also:
    
    isEqualTo(ptolemy.data.Token)
  - isEqualTo
```
public final BooleanToken isEqualTo(Token rightArgument)
                             throws IllegalActionException
```
    Test for equality of the values of this Token and the argument Token. The argument and this token are converted to equivalent types, and then compared. Generally, this is the higher of the type of this token and the argument type. This method defers to the _isEqualTo method to perform a type-specific equality check. Derived classes should override that method to provide type specific actions for equality testing.
    
    Overrides:
    
    isEqualTo in class Token
    
    Parameters:
    
    rightArgument - The token with which to test equality.
    
    Returns:
    
    A BooleanToken which contains the result of the test.
    
    Throws:
    
    IllegalActionException - If this method is not supported by the derived class.
    
    See Also:
    
    isCloseTo(ptolemy.data.Token, double)
  - 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.
    
    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, or the operation is not supported by this matrix class.
  - longMatrix
```
public long[][] longMatrix()
                    throws IllegalActionException
```
    Return the content of this matrix as a 2-D long matrix. In this base class, just throw an exception.
    
    Returns:
    
    A 2-D long matrix.
    
    Throws:
    
    IllegalActionException - If the token cannot be represented as requested (always thrown in this base class).
  - matrixToArray
```
public static ArrayToken matrixToArray(MatrixToken matrix)
```
    Create a new instance of ArrayToken that contains the values in the specified matrix.
    
    Parameters:
    
    matrix - The given matrix.
    
    Returns:
    
    An array.
  - matrixToArrayReturnType
```
public static Type matrixToArrayReturnType(Type type)
```
    Return the (exact) return type of the toArray function above. If the argument is a matrix type, then return an array type of its element type, otherwise return BaseType.UNKNOWN.
    
    Parameters:
    
    type - The type of the argument to the corresponding function.
    
    Returns:
    
    The type of the value returned from the corresponding function.
  - modulo
```
public final Token modulo(Token rightArgument)
                   throws IllegalActionException
```
    Return a new token whose value is this token modulo the value of the argument token.
    
    Overrides:
    
    modulo in class Token
    
    Parameters:
    
    rightArgument - The token that performs modulo on this token.
    
    Returns:
    
    A new token containing the result.
    
    Throws:
    
    IllegalActionException - If the operation does not make sense for the given types.
  - moduloReverse
```
public final Token moduloReverse(Token leftArgument)
                          throws IllegalActionException
```
    Return a new token whose value is the value of the argument token modulo the value of this token. Since modulo is not supported for matrices, this always throws an exception.
    
    Overrides:
    
    moduloReverse in class Token
    
    Parameters:
    
    leftArgument - The token to apply modulo to by the value of this token.
    
    Returns:
    
    A new token containing the result.
    
    Throws:
    
    IllegalActionException - If the the operation does not make sense for the given types.
  - multiply
```
public final Token multiply(Token rightArgument)
                     throws IllegalActionException
```
    Return a new token whose value is the value of this token multiplied by the value of the argument token. Type conversion also occurs here, so that the operation is performed at the least type necessary to ensure precision. The returned type is the same as the type chosen for the operation. Generally, this is higher of the type of this token and the argument type. This class overrides the base class to perform conversion from scalars to matrices appropriately for matrix multiplication. Subclasses should not generally override this method, but override the protected _multiply() method to ensure that type conversion is performed consistently.
    
    Overrides:
    
    multiply in class Token
    
    Parameters:
    
    rightArgument - The token to multiply this token by.
    
    Returns:
    
    A new token containing the result.
    
    Throws:
    
    IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.
  - multiplyReverse
```
public final Token multiplyReverse(Token leftArgument)
                            throws IllegalActionException
```
    Return a new token whose value is the value of the argument token multiplied by the value of this token. Type resolution also occurs here, with the returned token type chosen to achieve a lossless conversion.
    
    Overrides:
    
    multiplyReverse in class Token
    
    Parameters:
    
    leftArgument - The token to be multiplied by the value of this token.
    
    Returns:
    
    A new token containing the result.
    
    Throws:
    
    IllegalActionException - If the argument token is not of a type that can be multiplied by this token.
  - oneRight
```
public Token oneRight()
               throws IllegalActionException
```
    Return a new Token representing the right multiplicative identity. The returned token contains an identity matrix whose dimensions are the same as the number of columns of the matrix contained in this token. The implementation in this base class just throws an exception. This method should be overridden in the subclass when the right multiplicative identity exists.
    
    Returns:
    
    A new MatrixToken containing the right multiplicative identity.
    
    Throws:
    
    IllegalActionException - If this method is not supported by the derived class.
  - split
```
public MatrixToken[][] split(int[] rows,
                             int[] columns)
                      throws IllegalActionException
```
    Split this matrix into multiple matrices. In this base class, this method simply throws an exception. Derived classes provide the implementation.
    The matrices are produced from submatrices extracted left-to-right, top-to-bottom, in a raster scan pattern. For example, if rowSplit = {1, 2}, columnSplit = {2, 1}, and the input matrix is as follows:
    1 2 3 4 5 6 7 8 9
    then the first matrix out is a column vector:
    1 4
    The second matrix out is
    2 3 5 6
    The third is
    7
    (a 1x1 matrix) and the fourth is
    8 9
    a row vector. If the input does not have enough elements to fill the specified output matrices, then zeros (of the same type as the input elements) are used. If the input is larger than is required to fill the specified output, then the additional values are discarded.
    Parameters:
    
    rows - The number of rows per submatrix.
    
    columns - The number of columns per submatrix.
    
    Returns:
    
    An array of matrix tokens.
    
    Throws:
    
    IllegalActionException - If the operation is not supported.
  - subtract
```
public final Token subtract(Token rightArgument)
                     throws IllegalActionException
```
    Return a new token whose value is the value of the argument token subtracted from the value of this token. Type conversion also occurs here, so that the operation is performed at the least type necessary to ensure precision. The returned type is the same as the type chosen for the operation. Generally, this is higher of the type of this token and the argument type. Subclasses should not override this method, but override the protected _subtract() method to ensure that type conversion is performed consistently.
    
    Overrides:
    
    subtract in class Token
    
    Parameters:
    
    rightArgument - The token to subtract from this token.
    
    Returns:
    
    A new token containing the result.
    
    Throws:
    
    IllegalActionException - If the argument token and this token are of incomparable types, or the operation does not make sense for the given types.
  - subtractReverse
```
public final Token subtractReverse(Token leftArgument)
                            throws IllegalActionException
```
    Return a new token whose value is the value of this token subtracted from the value of the argument token. Type resolution also occurs here, with the returned token type chosen to achieve a lossless conversion.
    
    Overrides:
    
    subtractReverse in class Token
    
    Parameters:
    
    leftArgument - The token to subtract this token from.
    
    Returns:
    
    A new token containing the result.
    
    Throws:
    
    IllegalActionException - If the argument token is not of a type that can be subtracted to this token, or the units of this token and the argument token are not the same.
  - toArray
```
public ArrayToken toArray()
```
    Return an ArrayToken containing the all the values of this matrix token. The type of the tokens in the array is consistent with the type of this token.
    
    Returns:
    
    An ArrayToken containing the elements of this matrix in row-scanned order.
  - toArrayColumnMajor
```
public ArrayToken toArrayColumnMajor()
```
    Return an ArrayToken containing the all the values of this matrix token. The type of the tokens in the array is consistent with the type of this token.
    
    Returns:
    
    An ArrayToken containing the elements of this matrix in column-scanned order.
  - toArrayReturnType
```
public static Type toArrayReturnType(Type type)
```
    Return the (exact) return type of the toArray function above. If the argument is a matrix type, then return an array type of its element type, otherwise return BaseType.UNKNOWN.
    
    Parameters:
    
    type - The type of the argument to the corresponding function.
    
    Returns:
    
    The type of the value returned from the corresponding function.
  - toString
```
public java.lang.String toString()
```
    Return the value of this token as a string that can be parsed by the expression language to recover a token with the same value. The expression starts and ends with a square bracket. The matrix is scanned starting from the upper left and proceeding across each row. Each element in the row is separated by a comma, and the end of a row is represented by a semicolon. The value of each element is obtained using its toString method.
    
    Overrides:
    
    toString in class Token
    
    Returns:
    
    A String representing a matrix similar to Matlab.
  - _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 guaranteed by the caller that the type of the argument is the same as the type of this class, and that the matrices have appropriate dimensions. This method should be overridden in derived classes to provide type-specific operation and return a token of the appropriate subclass.
    
    Parameters:
    
    rightArgument - The token to add to this token.
    
    Returns:
    
    A new Token containing the result.
    
    Throws:
    
    IllegalActionException - If this method 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 to the value of each element of this Token. It is guaranteed by the caller that the type of the argument is the same as the type of each element of this class.
    
    Parameters:
    
    rightArgument - The token to add to this token.
    
    Returns:
    
    A new Token containing the result.
    
    Throws:
    
    IllegalActionException - If this operation is not supported by the derived class.
  - _divideElement
```
protected MatrixToken _divideElement(Token rightArgument)
                              throws IllegalActionException
```
    Return a new token whose elements are the result of dividing the elements of this token by the argument. It is guaranteed by the caller that the type of the argument is the same as the type of each element of this class.
    
    Parameters:
    
    rightArgument - The token that divides this token.
    
    Returns:
    
    A new Token containing the result.
    
    Throws:
    
    IllegalActionException - If this operation is not supported by the derived class.
  - _isCloseTo
```
protected BooleanToken _isCloseTo(MatrixToken token,
                                  double distance)
                           throws IllegalActionException
```
    Test whether the value of this token is close to the first argument, where "close" means that the distance between their elements is less than or equal to the second argument. This base class delegates to the token class corresponding to the matrix elements, using its isCloseTo() method. If the two matrices do have the same dimension, then this method returns false.
    
    Parameters:
    
    token - The matrix token to compare to this token.
    
    distance - The specified distance.
    
    Returns:
    
    True if every element of the specified matrix is within the specified distance of the corresponding element of this matrix.
    
    Throws:
    
    IllegalActionException - If a derived class throws it.
  - _isEqualTo
```
protected BooleanToken _isEqualTo(MatrixToken rightArgument)
                           throws IllegalActionException
```
    Test for equality of the values of this Token and the argument Token. It is guaranteed by the caller that the type and dimensions of the argument is the same as the type of this class. This method can be overridden in derived classes to provide type-specific operation and return a token of the appropriate subclass. In this base class, this method delegates to equals().
    
    Parameters:
    
    rightArgument - The token to compare to this token.
    
    Returns:
    
    A true-valued token if the argument is equal to this matrix.
    
    Throws:
    
    IllegalActionException - If this method is not supported by a derived class.
  - _elementIsNil
```
protected void _elementIsNil(int element)
```
    Add the element to the _nils Set. Subclasses should call this when they encounter a nil token during construction. If _nils is null, this method constructs _nils as a new HashSet.
    
    Parameters:
    
    element - The element index. The format is rows * columnCount + column.
  - _moduloElement
```
protected MatrixToken _moduloElement(Token rightArgument)
                              throws IllegalActionException
```
    Return a new token whose elements are the modulo of the elements of this token by the argument. It is guaranteed by the caller that the type of the argument is the same as the type of each element of this class.
    
    Parameters:
    
    rightArgument - The token that performs modulo on 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 guaranteed by the caller that the type of the argument is the same as the type of this class, and that the matrices have appropriate dimensions. This method should be overridden in derived classes to provide type-specific operation and return a token of the appropriate subclass.
    
    Parameters:
    
    rightArgument - The token to multiply this token by.
    
    Returns:
    
    A new Token containing the result.
    
    Throws:
    
    IllegalActionException - If this method is not supported by the derived class.
  - _multiplyElement
```
protected MatrixToken _multiplyElement(Token rightArgument)
                                throws IllegalActionException
```
    Return a new token whose value is the value of this token multiplied by the value of the argument scalar token. This method should be overridden in derived classes to provide type specific actions for multiply.
    
    Parameters:
    
    rightArgument - The token to multiply this token by.
    
    Returns:
    
    A new Token containing the result that is of the same class as this token.
    
    Throws:
    
    IllegalActionException - If this method 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 from the value of this token. It is guaranteed by the caller that the type of the argument is the same as the type of this class, and that the matrices have appropriate dimensions. This method should be overridden in derived classes to provide type-specific operation and return a token of the appropriate subclass.
    
    Parameters:
    
    rightArgument - The token to subtract from this token.
    
    Returns:
    
    A new Token containing the result.
    
    Throws:
    
    IllegalActionException - If this method 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 guaranteed by the caller that the type of the argument is the same as the type of each element of this class.
    
    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 each element of this Token subtracted from the value the argument Token. It is guaranteed by the caller that the type of the argument is the same as the type of each element of this class.
    
    Parameters:
    
    rightArgument - The token to subtract this token from.
    
    Returns:
    
    A new Token containing the result.
    
    Throws:
    
    IllegalActionException - If this operation is not supported by the derived class.

Class MatrixToken

Field Summary

Fields inherited from class ptolemy.data.Token

Constructor Summary

Method Summary

Methods inherited from class ptolemy.data.Token

Methods inherited from class java.lang.Object

Field Detail

DO_COPY

DO_NOT_COPY

_nils

Constructor Detail

MatrixToken

Method Detail

add

addReverse

arrayToMatrix

arrayToMatrix

arrayToMatrixReturnType

booleanMatrix

complexMatrix

create

createSequence

createSequenceReturnType

createTokenSequence

crop

determineSequenceLength

divide

divideReverse

doubleMatrix

fixMatrix

getColumnCount

getElementAsToken

getElementType

getRowCount

intMatrix

isCloseTo

isEqualTo

join

longMatrix

matrixToArray

matrixToArrayReturnType

modulo

moduloReverse

multiply

multiplyReverse

oneRight

split

subtract

subtractReverse

toArray

toArrayColumnMajor

toArrayReturnType

toString

_add

_addElement

_divideElement

_isCloseTo

_isEqualTo

_elementIsNil

_moduloElement

_multiply

_multiplyElement

_subtract

_subtractElement

_subtractElementReverse