ptolemy.math

Class FractionMatrixMath

java.lang.Object

ptolemy.math.FractionMatrixMath

public class FractionMatrixMath
extends java.lang.Object

A library for mathematical operations on matrices of Fractions.

Rows and column numbers of matrices are specified with zero-based indices. All calls expect matrix arguments to be non-null. In addition, all rows of the matrix are expected to have the same number of columns.

Since:

Ptolemy II 5.0

Version:

$Id$

Author:

Adam Cataldo

Pt.AcceptedRating:

Red (cxh)

Pt.ProposedRating:

Red (acataldo)

Method Summary

Modifier and Type	Method and Description
protected static void	_checkSameDimension(java.lang.String caller, Fraction[][] matrix1, Fraction[][] matrix2) Check that the two matrix arguments are of the same dimension.
protected static int	_checkSquare(java.lang.String caller, Fraction[][] matrix) Check that the argument matrix is a square matrix.
protected static int	_columns(Fraction[][] matrix) Return the number of columns of a matrix.
protected static java.lang.String	_dimensionString(Fraction[][] matrix) Return a string that describes the number of rows and columns.
protected static int	_rows(Fraction[][] matrix) Return the number of rows of a matrix.
static Fraction[][]	add(Fraction[][] matrix, Fraction z) Return a new matrix that is constructed from the argument by adding the second argument to every element.
static Fraction[][]	add(Fraction[][] matrix1, Fraction[][] matrix2) Return a new matrix that is constructed from the argument by adding the second matrix to the first one.
static Fraction[][]	allocCopy(Fraction[][] matrix) Return a new matrix that is a copy of the matrix argument.
static Fraction[][]	crop(Fraction[][] matrix, int rowStart, int colStart, int rowSpan, int colSpan) Return a new matrix that is a sub-matrix of the input matrix argument.
static Fraction[][]	diag(Fraction[] array) Return a new matrix that is constructed by placing the elements of the input array on the diagonal of the square matrix, starting from the top left corner down to the bottom right corner.
static Fraction[][]	divide(Fraction[][] matrix, Fraction z) Return a new matrix that is constructed from the argument by dividing the second argument to every element.
static Fraction[][]	divideElements(Fraction[][] matrix1, Fraction[][] matrix2) Return a new matrix that is constructed by element by element division of the two matrix arguments.
static Fraction[]	fromMatrixToArray(Fraction[][] matrix) Return a new array that is filled with the contents of the matrix.
static Fraction[]	fromMatrixToArray(Fraction[][] matrix, int maxRow, int maxCol) Return a new array that is filled with the contents of the matrix.
static Fraction[][]	identity(int dim) Return an new identity matrix with the specified dimension.
static Fraction[][]	multiply(Fraction[][] matrix, Fraction scaleFactor) Return a new matrix that is constructed by multiplying the matrix by a scaleFactor.
static Fraction[]	multiply(Fraction[][] matrix, Fraction[] array) Return a new array that is constructed from the argument by post-multiplying the matrix by an array (treated as a column vector).
static Fraction[][]	multiply(Fraction[][] matrix1, Fraction[][] matrix2) Return a new matrix that is constructed from the argument by multiplying the first matrix by the second one.
static Fraction[]	multiply(Fraction[] array, Fraction[][] matrix) Return a new array that is constructed from the argument by pre-multiplying the matrix by an array (treated as a row vector).
static Fraction[][]	multiplyElements(Fraction[][] matrix1, Fraction[][] matrix2) Return a new matrix that is constructed by element by element multiplication of the two matrix arguments.
static Fraction[][]	negative(Fraction[][] matrix) Return a new matrix that is the additive inverse of the argument matrix.
static Fraction[][]	subtract(Fraction[][] matrix1, Fraction[][] matrix2) Return a new matrix that is constructed from the argument by subtracting the second matrix from the first one.
static Fraction	sum(Fraction[][] matrix) Return the sum of the elements of a matrix.
static double[][]	toDoubleMatrix(Fraction[][] matrix) Return a new matrix that is formed by converting the Fractions in the argument matrix to doubles.
static Fraction[][]	toMatrixFromArray(Fraction[] array, int rows, int cols) Return a new matrix of Fractions that is initialized from a 1-D array.
static java.lang.String	toString(Fraction[][] matrix) Return a new String representing the matrix, formatted as in Java array initializers.
static java.lang.String	toString(Fraction[][] matrix, java.lang.String elementDelimiter, java.lang.String matrixBegin, java.lang.String matrixEnd, java.lang.String vectorBegin, java.lang.String vectorDelimiter, java.lang.String vectorEnd) Return a new String representing the matrix, formatted as specified by the ArrayStringFormat argument.
static Fraction	trace(Fraction[][] matrix) Return the trace of a square matrix, which is the sum of the diagonal entries A11 + A22 + ... + Ann Throw an IllegalArgumentException if the matrix is not square.
static Fraction[][]	transpose(Fraction[][] matrix) Return a new matrix that is constructed by transposing the input matrix.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

add

public static final Fraction[][] add(Fraction[][] matrix,
                                     Fraction z)

Return a new matrix that is constructed from the argument by adding the second argument to every element.

Parameters:

matrix - A matrix of Fractions.

z - The Fraction to add.

Returns:

A new matrix of Fractions.

add

public static final Fraction[][] add(Fraction[][] matrix1,
                                     Fraction[][] matrix2)

Return a new matrix that is constructed from the argument by adding the second matrix to the first one. If the two matrices are not the same size, throw an IllegalArgumentException.

Parameters:

matrix1 - The first matrix of Fractions.

matrix2 - The second matrix of Fractions.

Returns:

A new matrix of Fractions.

allocCopy

public static final Fraction[][] allocCopy(Fraction[][] matrix)

Return a new matrix that is a copy of the matrix argument.

Parameters:

matrix - A matrix of Fractions.

Returns:

A new matrix of Fractions.

crop

public static final Fraction[][] crop(Fraction[][] matrix,
                                      int rowStart,
                                      int colStart,
                                      int rowSpan,
                                      int colSpan)

Return a new matrix that is a sub-matrix of the input matrix argument. The row and column from which to start and the number of rows and columns to span are specified.

Parameters:

matrix - A matrix of Fractions.

rowStart - An int specifying which row to start on.

colStart - An int specifying which column to start on.

rowSpan - An int specifying how many rows to copy.

colSpan - An int specifying how many columns to copy.

diag

public static final Fraction[][] diag(Fraction[] array)

Return a new matrix that is constructed by placing the elements of the input array on the diagonal of the square matrix, starting from the top left corner down to the bottom right corner. All other elements are zero. The size of of the matrix is n x n, where n is the length of the input array.

divide

public static final Fraction[][] divide(Fraction[][] matrix,
                                        Fraction z)

Return a new matrix that is constructed from the argument by dividing the second argument to every element.

Parameters:

matrix - A matrix of Fractions.

z - The Fraction to divide by.

Returns:

A new matrix of Fractions.

divideElements

public static final Fraction[][] divideElements(Fraction[][] matrix1,
                                                Fraction[][] matrix2)

Return a new matrix that is constructed by element by element division of the two matrix arguments. Each element of the first matrix is divided by the corresponding element of the second matrix. If the two matrices are not the same size, throw an IllegalArgumentException.

fromMatrixToArray

public static final Fraction[] fromMatrixToArray(Fraction[][] matrix)

Return a new array that is filled with the contents of the matrix. The Fractions are stored row by row, i.e. using the notation (row, column), the entries of the array are in the following order for a (m, n) matrix : (0, 0), (0, 1), (0, 2), ... , (0, n-1), (1, 0), (1, 1), ..., (m-1)(n-1)

Parameters:

matrix - A matrix of Fractions.

Returns:

A new array of Fractions.

fromMatrixToArray

public static final Fraction[] fromMatrixToArray(Fraction[][] matrix,
                                                 int maxRow,
                                                 int maxCol)

Return a new array that is filled with the contents of the matrix. The maximum numbers of rows and columns to copy are specified so that entries lying outside of this range can be ignored. The maximum rows to copy cannot exceed the number of rows in the matrix, and the maximum columns to copy cannot exceed the number of columns in the matrix. The Fractions are stored row by row, i.e. using the notation (row, column), the entries of the array are in the following order for a matrix, limited to m rows and n columns : (0, 0), (0, 1), (0, 2), ... , (0, n-1), (1, 0), (1, 1), ..., (m-1)(n-1)

Parameters:

matrix - A matrix of Fractions.

Returns:

A new array of Fractions.

identity

public static final Fraction[][] identity(int dim)

Return an new identity matrix with the specified dimension. The matrix is square, so only one dimension specifier is needed.

Returns:

Identity matrix in fractions

multiply

public static final Fraction[][] multiply(Fraction[][] matrix,
                                          Fraction scaleFactor)

Return a new matrix that is constructed by multiplying the matrix by a scaleFactor.

Parameters:

matrix - The matrix of Fractions.

scaleFactor - The Fraction to multiply by.

Returns:

The resulting matrix of Fractions.

multiply

public static final Fraction[] multiply(Fraction[] array,
                                        Fraction[][] matrix)

Return a new array that is constructed from the argument by pre-multiplying the matrix by an array (treated as a row vector). The number of rows of the matrix must equal the number of elements in the array. The returned array will have a length equal to the number of columns of the matrix.

Parameters:

array - The array of Fractions.

matrix - The matrix of Fractions.

Returns:

The resulting matrix of Fractions.

multiply

public static final Fraction[] multiply(Fraction[][] matrix,
                                        Fraction[] array)

Return a new array that is constructed from the argument by post-multiplying the matrix by an array (treated as a column vector). The number of columns of the matrix must equal the number of elements in the array. The returned array will have a length equal to the number of rows of the matrix.

Parameters:

matrix - The matrix of Fractions.

array - The array of Fractions.

Returns:

The resulting matrix of Fractions.

multiply

public static final Fraction[][] multiply(Fraction[][] matrix1,
                                          Fraction[][] matrix2)
                                   throws java.lang.ArithmeticException

Return a new matrix that is constructed from the argument by multiplying the first matrix by the second one. Note this operation is not commutative, so care must be taken in the ordering of the arguments. The number of columns of matrix1 must equal the number of rows of matrix2. If matrix1 is of size m x n, and matrix2 is of size n x p, the returned matrix will have size m x p.

Note that this method is different from the other multiply() methods in that this method does not do pointwise multiplication.

Parameters:

matrix1 - The first matrix of Fractions.

matrix2 - The second matrix of Fractions.

Returns:

A new matrix of ints.

Throws:

java.lang.ArithmeticException - If the matrix dimensions don't match up.

See Also:

multiplyElements(Fraction[][], Fraction[][])

multiplyElements

public static final Fraction[][] multiplyElements(Fraction[][] matrix1,
                                                  Fraction[][] matrix2)

Return a new matrix that is constructed by element by element multiplication of the two matrix arguments. If the two matrices are not the same size, throw an IllegalArgumentException.

Note that this method does pointwise matrix multiplication.

Parameters:

matrix1 - The first matrix of Fractions.

matrix2 - The second matrix of Fractions.

Returns:

A new matrix of ints.

negative

public static final Fraction[][] negative(Fraction[][] matrix)

Return a new matrix that is the additive inverse of the argument matrix.

Parameters:

matrix - the input matrix of Fractions.

Returns:

the output matrix of Fractions.

subtract

public static final Fraction[][] subtract(Fraction[][] matrix1,
                                          Fraction[][] matrix2)

Return a new matrix that is constructed from the argument by subtracting the second matrix from the first one. If the two matrices are not the same size, throw an IllegalArgumentException.

Parameters:

matrix1 - The matrix to be subtracted from.

matrix2 - The matrix to subtract.

Returns:

The difference matrix.

sum

public static final Fraction sum(Fraction[][] matrix)

Return the sum of the elements of a matrix.

Parameters:

matrix - The input matrix.

Returns:

The sum of the elements of the matrix.

toDoubleMatrix

public static final double[][] toDoubleMatrix(Fraction[][] matrix)

Return a new matrix that is formed by converting the Fractions in the argument matrix to doubles.

Parameters:

matrix - An matrix of Fractions.

Returns:

A new matrix of doubles.

toMatrixFromArray

public static final Fraction[][] toMatrixFromArray(Fraction[] array,
                                                   int rows,
                                                   int cols)

Return a new matrix of Fractions that is initialized from a 1-D array. The format of the array must be (0, 0), (0, 1), ..., (0, n-1), (1, 0), (1, 1), ..., (m-1, n-1) where the output matrix is to be m x n and entries are denoted by (row, column).

Parameters:

array - An array of Fraction.

rows - An integer representing the number of rows of the new matrix.

cols - An integer representing the number of columns of the new matrix.

Returns:

A new matrix of Fractions.

toString

public static final java.lang.String toString(Fraction[][] matrix)

Return a new String representing the matrix, formatted as in Java array initializers.

toString

public static final java.lang.String toString(Fraction[][] matrix,
                                              java.lang.String elementDelimiter,
                                              java.lang.String matrixBegin,
                                              java.lang.String matrixEnd,
                                              java.lang.String vectorBegin,
                                              java.lang.String vectorDelimiter,
                                              java.lang.String vectorEnd)

Return a new String representing the matrix, formatted as specified by the ArrayStringFormat argument. To get a String in the Ptolemy expression language format, call this method with ArrayStringFormat.exprASFormat as the format argument.

trace

public static final Fraction trace(Fraction[][] matrix)

Return the trace of a square matrix, which is the sum of the diagonal entries A₁₁ + A₂₂ + ... + A_nn Throw an IllegalArgumentException if the matrix is not square. Note that the trace of a matrix is equal to the sum of its eigenvalues.

Parameters:

matrix - A square matrix.

Returns:

The trace of this matrix.

transpose

public static final Fraction[][] transpose(Fraction[][] matrix)

Return a new matrix that is constructed by transposing the input matrix. If the input matrix is m x n, the output matrix will be n x m.

Parameters:

matrix - The input matrix.

Returns:

The matrix transpose.

_checkSameDimension

protected static final void _checkSameDimension(java.lang.String caller,
                                                Fraction[][] matrix1,
                                                Fraction[][] matrix2)

Check that the two matrix arguments are of the same dimension. If they are not, an IllegalArgumentException is thrown.

Parameters:

caller - A string representing the caller method name.

matrix1 - A matrix of ints.

matrix2 - A matrix of ints.

_checkSquare

protected static final int _checkSquare(java.lang.String caller,
                                        Fraction[][] matrix)

Check that the argument matrix is a square matrix. If the matrix is not square, an IllegalArgumentException is thrown.

Parameters:

caller - A string representing the caller method name.

matrix - A matrix of Fractions.

Returns:

The dimension of the square matrix.

_columns

protected static final int _columns(Fraction[][] matrix)

Return the number of columns of a matrix.

Parameters:

matrix - The matrix.

Returns:

The number of columns.

_dimensionString

protected static final java.lang.String _dimensionString(Fraction[][] matrix)

Return a string that describes the number of rows and columns.

Parameters:

matrix - The matrix that is to be described.

Returns:

a string describing the dimensions of this matrix.

_rows

protected static final int _rows(Fraction[][] matrix)

Return the number of rows of a matrix.