ptolemy.math

Class FloatMatrixMath

java.lang.Object

ptolemy.math.FloatMatrixMath

public class FloatMatrixMath
extends java.lang.Object

This class provides a library for mathematical operations on matrices of floats. 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 1.0

Version:

$Id$

Author:

Jeff Tsay

Pt.AcceptedRating:

Yellow (ctsay)

Pt.ProposedRating:

Yellow (ctsay)

Method Summary

Modifier and Type	Method and Description
protected static void	_checkSameDimension(java.lang.String caller, float[][] matrix1, float[][] matrix2) Check that the two matrix arguments are of the same dimension.
protected static int	_checkSquare(java.lang.String caller, float[][] matrix) Check that the argument matrix is a square matrix.
protected static int	_columns(float[][] matrix) Return the number of columns of a matrix.
protected static java.lang.String	_dimensionString(float[][] matrix) Return a string that describes the number of rows and columns.
protected static java.lang.Object[]	_orthogonalizeRows(float[][] rowArrays) Given a set of row vectors rowArrays[0] ... rowArrays[n-1], compute : A new set of row vectors out[0] ... out[n-1] which are the orthogonalized versions of each input row vector.
protected static int	_rows(float[][] matrix) Return the number of rows of a matrix.
static float[][]	add(float[][] matrix, float z) Return a new matrix that is constructed from the argument by adding the second argument to every element.
static float[][]	add(float[][] matrix1, float[][] matrix2) Return a new matrix that is constructed from the argument by adding the second matrix to the first one.
static float[][]	allocCopy(float[][] matrix) Return a new matrix that is a copy of the matrix argument.
static float[][]	applyBinaryOperation(FloatBinaryOperation op, float[][] matrix, float z) Return a new array that is formed by applying an instance of a FloatBinaryOperation to each element in the input matrix, using the matrix elements as the left operands and z as the right operand in all cases (op.operate(matrix[i][j], z)).
static float[][]	applyBinaryOperation(FloatBinaryOperation op, float[][] matrix1, float[][] matrix2) Return a new array that is formed by applying an instance of a FloatBinaryOperation to the two matrices, element by element, using the elements of the first matrix as the left operands and the elements of the second matrix as the right operands.
static float[][]	applyBinaryOperation(FloatBinaryOperation op, float z, float[][] matrix) Return a new array that is formed by applying an instance of a FloatBinaryOperation to each element in the input matrix, using z as the left operand in all cases and the matrix elements as the right operands (op.operate(z, matrix[i][j])).
static float[][]	applyUnaryOperation(FloatUnaryOperation op, float[][] matrix) Return a new array that is formed by applying an instance of a FloatUnaryOperation to each element in the input matrix (op.operate(matrix[i][j])).
static float[][]	crop(float[][] matrix, int rowStart, int colStart, int rowSpan, int colSpan) Return a new matrix that is a sub-matrix of the input matrix argument.
static float	determinant(float[][] matrix) Return the determinant of a square matrix.
static float[][]	diag(float[] 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 float[][]	divide(float[][] matrix, float z) Return a new matrix that is constructed from the argument by dividing the second argument to every element.
static float[][]	divideElements(float[][] matrix1, float[][] matrix2) Return a new matrix that is constructed by element by element division of the two matrix arguments.
static float[]	fromMatrixToArray(float[][] matrix) Return a new array that is filled with the contents of the matrix.
static float[]	fromMatrixToArray(float[][] matrix, int maxRow, int maxCol) Return a new array that is filled with the contents of the matrix.
static float[][]	hilbert(int dim) Return a new matrix, which is defined by Aij = 1/(i+j+1), the Hilbert matrix.
static float[][]	identity(int dim) Return an new identity matrix with the specified dimension.
static float[][]	inverse(float[][] A) Return a new matrix that is constructed by inverting the input matrix.
static void	matrixCopy(float[][] srcMatrix, float[][] destMatrix) Replace the first matrix argument elements with the values of the second matrix argument.
static void	matrixCopy(float[][] srcMatrix, int srcRowStart, int srcColStart, float[][] destMatrix, int destRowStart, int destColStart, int rowSpan, int colSpan) Replace the first matrix argument's values, in the specified row and column range, with the second matrix argument's values, starting from specified row and column of the second matrix.
static float[][]	multiply(float[][] matrix, float scaleFactor) Return a new matrix that is constructed by multiplying the matrix by a scaleFactor.
static float[]	multiply(float[][] matrix, float[] array) Return a new array that is constructed from the argument by pre-multiplying the array (treated as a row vector) by a matrix.
static float[][]	multiply(float[][] matrix1, float[][] matrix2) Return a new matrix that is constructed from the argument by multiplying the first matrix by the second one.
static float[]	multiply(float[] array, float[][] matrix) Return a new array that is constructed from the argument by post-multiplying the matrix by an array (treated as a row vector).
static float[][]	multiplyElements(float[][] matrix1, float[][] matrix2) Return a new matrix that is constructed by element by element multiplication of the two matrix arguments.
static float[][]	negative(float[][] matrix) Return a new matrix that is the additive inverse of the argument matrix.
static float[][]	orthogonalizeColumns(float[][] matrix) Return a new matrix that is formed by orthogonalizing the columns of the input matrix (the column vectors are orthogonal).
static float[][]	orthogonalizeRows(float[][] matrix) Return a new matrix that is formed by orthogonalizing the rows of the input matrix (the row vectors are orthogonal).
static float[][]	orthonormalizeColumns(float[][] matrix) Return a new matrix that is formed by orthogonalizing the columns of the input matrix (the column vectors are orthogonal and have norm 1).
static float[][]	orthonormalizeRows(float[][] matrix) Return a new matrix that is formed by orthonormalizing the rows of the input matrix (the row vectors are orthogonal and have norm 1).
static float[][][]	qr(float[][] matrix) Return a pair of matrices that are the decomposition of the input matrix (which must have linearly independent column vectors), which is m x n, into the matrix product of Q, which is m x n with orthonormal column vectors, and R, which is an invertible n x n upper triangular matrix.
static float[][]	subtract(float[][] matrix1, float[][] matrix2) Return a new matrix that is constructed from the argument by subtracting the second matrix from the first one.
static float	sum(float[][] matrix) Return the sum of the elements of a matrix.
static Complex[][]	toComplexMatrix(float[][] matrix) Return a new matrix that is formed by converting the floats in the argument matrix to complex numbers.
static double[][]	toDoubleMatrix(float[][] matrix) Return a new matrix that is formed by converting the floats in the argument matrix to doubles.
static int[][]	toIntegerMatrix(float[][] matrix) Return a new matrix that is formed by converting the floats in the argument matrix to integers.
static long[][]	toLongMatrix(float[][] matrix) Return a new matrix that is formed by converting the floats in the argument matrix to longs.
static float[][]	toMatrixFromArray(float[] array, int rows, int cols) Return a new matrix of floats that is initialized from a 1-D array.
static java.lang.String	toString(float[][] matrix) Return a new String representing the matrix, formatted as in Java array initializers.
static java.lang.String	toString(float[][] 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 float	trace(float[][] 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 float[][]	transpose(float[][] matrix) Return a new matrix that is constructed by transposing the input matrix.
static boolean	within(float[][] matrix1, float[][] matrix2, float distance) Return true if the elements of the two matrices differ by no more than the specified distance.
static boolean	within(float[][] matrix1, float[][] matrix2, float[][] errorMatrix) Return true if the elements of the two matrices differ by no more than the specified distances.

Methods inherited from class java.lang.Object

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

Method Detail

add

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

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

Parameters:

matrix - A matrix of floats.

z - The float number to add.

Returns:

A new matrix of floats.

add

public static final float[][] add(float[][] matrix1,
                                  float[][] 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 floats.

matrix2 - The second matrix of floats.

Returns:

A new matrix of floats.

allocCopy

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

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

Parameters:

matrix - A matrix of floats.

Returns:

A new matrix of floats.

applyBinaryOperation

public static final float[][] applyBinaryOperation(FloatBinaryOperation op,
                                                   float z,
                                                   float[][] matrix)

Return a new array that is formed by applying an instance of a FloatBinaryOperation to each element in the input matrix, using z as the left operand in all cases and the matrix elements as the right operands (op.operate(z, matrix[i][j])).

applyBinaryOperation

public static final float[][] applyBinaryOperation(FloatBinaryOperation op,
                                                   float[][] matrix,
                                                   float z)

Return a new array that is formed by applying an instance of a FloatBinaryOperation to each element in the input matrix, using the matrix elements as the left operands and z as the right operand in all cases (op.operate(matrix[i][j], z)).

applyBinaryOperation

public static final float[][] applyBinaryOperation(FloatBinaryOperation op,
                                                   float[][] matrix1,
                                                   float[][] matrix2)

Return a new array that is formed by applying an instance of a FloatBinaryOperation to the two matrices, element by element, using the elements of the first matrix as the left operands and the elements of the second matrix as the right operands. (op.operate(matrix1[i][j], matrix2[i][j])). If the matrices are not the same size, throw an IllegalArgumentException.

applyUnaryOperation

public static final float[][] applyUnaryOperation(FloatUnaryOperation op,
                                                  float[][] matrix)

Return a new array that is formed by applying an instance of a FloatUnaryOperation to each element in the input matrix (op.operate(matrix[i][j])).

crop

public static final float[][] crop(float[][] 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 floats.

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.

determinant

public static final float determinant(float[][] matrix)

Return the determinant of a square matrix. If the matrix is not square, throw an IllegalArgumentException. This algorithm uses LU decomposition, and is taken from [1]

diag

public static final float[][] diag(float[] 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 float[][] divide(float[][] matrix,
                                     float z)

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

Parameters:

matrix - A matrix of floats.

z - The float number to divide.

Returns:

A new matrix of floats.

divideElements

public static final float[][] divideElements(float[][] matrix1,
                                             float[][] 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 float[] fromMatrixToArray(float[][] matrix)

Return a new array that is filled with the contents of the matrix. The floats 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 floats.

Returns:

A new array of floats.

fromMatrixToArray

public static final float[] fromMatrixToArray(float[][] 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 floats 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 floats.

Returns:

A new array of floats.

hilbert

public static final float[][] hilbert(int dim)

Return a new matrix, which is defined by Aij = 1/(i+j+1), the Hilbert matrix. The matrix is square with one dimension specifier required. This matrix is useful because it always has an inverse.

identity

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

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

inverse

public static final float[][] inverse(float[][] A)

Return a new matrix that is constructed by inverting the input matrix. If the input matrix is singular, null is returned. This method is from [1]

matrixCopy

public static final void matrixCopy(float[][] srcMatrix,
                                    float[][] destMatrix)

Replace the first matrix argument elements with the values of the second matrix argument. The second matrix argument must be large enough to hold all the values of second matrix argument.

Parameters:

destMatrix - A matrix of floats, used as the destination.

srcMatrix - A matrix of floats, used as the source.

matrixCopy

public static final void matrixCopy(float[][] srcMatrix,
                                    int srcRowStart,
                                    int srcColStart,
                                    float[][] destMatrix,
                                    int destRowStart,
                                    int destColStart,
                                    int rowSpan,
                                    int colSpan)

Replace the first matrix argument's values, in the specified row and column range, with the second matrix argument's values, starting from specified row and column of the second matrix.

Parameters:

srcMatrix - A matrix of floats, used as the destination.

srcRowStart - An int specifying the starting row of the source.

srcColStart - An int specifying the starting column of the source.

destMatrix - A matrix of floats, used as the destination.

destRowStart - An int specifying the starting row of the dest.

destColStart - An int specifying the starting column of the dest.

rowSpan - An int specifying how many rows to copy.

colSpan - An int specifying how many columns to copy.

multiply

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

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

multiply

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

Return a new array that is constructed from the argument by pre-multiplying the array (treated as a row vector) by a matrix. 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.

multiply

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

Return a new array that is constructed from the argument by post-multiplying the matrix by an array (treated as a row 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.

multiply

public static final float[][] multiply(float[][] matrix1,
                                       float[][] matrix2)

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

matrix2 - The second matrix of floats.

Returns:

A new matrix of floats.

See Also:

multiplyElements(float[][], float[][])

multiplyElements

public static final float[][] multiplyElements(float[][] matrix1,
                                               float[][] 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. See multiply(float[][], float[][]) for standard matrix multiplication.

negative

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

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

orthogonalizeColumns

public static final float[][] orthogonalizeColumns(float[][] matrix)

Return a new matrix that is formed by orthogonalizing the columns of the input matrix (the column vectors are orthogonal). If not all columns are linearly independent, the output matrix will contain a column of zeros for all redundant input columns.

orthogonalizeRows

public static final float[][] orthogonalizeRows(float[][] matrix)

Return a new matrix that is formed by orthogonalizing the rows of the input matrix (the row vectors are orthogonal). If not all rows are linearly independent, the output matrix will contain a row of zeros for all redundant input rows.

orthonormalizeColumns

public static final float[][] orthonormalizeColumns(float[][] matrix)

Return a new matrix that is formed by orthogonalizing the columns of the input matrix (the column vectors are orthogonal and have norm 1). If not all columns are linearly independent, the output matrix will contain a column of zeros for all redundant input columns.

orthonormalizeRows

public static final float[][] orthonormalizeRows(float[][] matrix)

Return a new matrix that is formed by orthonormalizing the rows of the input matrix (the row vectors are orthogonal and have norm 1). If not all rows are linearly independent, the output matrix will contain a row of zeros for all redundant input rows.

qr

public static final float[][][] qr(float[][] matrix)

Return a pair of matrices that are the decomposition of the input matrix (which must have linearly independent column vectors), which is m x n, into the matrix product of Q, which is m x n with orthonormal column vectors, and R, which is an invertible n x n upper triangular matrix. Throw an IllegalArgumentException if the columns vectors of the input matrix are not linearly independent.

Parameters:

matrix - The input matrix of floats.

Returns:

The pair of newly allocated matrices of floats, out[0] = Q, out[1] = R.

subtract

public static final float[][] subtract(float[][] matrix1,
                                       float[][] 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.

sum

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

Return the sum of the elements of a matrix.

Returns:

The sum of the elements of the matrix.

toComplexMatrix

public static final Complex[][] toComplexMatrix(float[][] matrix)

Return a new matrix that is formed by converting the floats in the argument matrix to complex numbers. Each complex number has a real part equal to the value in the argument matrix and a zero imaginary part.

Parameters:

matrix - A matrix of floats.

Returns:

A new matrix of complex numbers.

toDoubleMatrix

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

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

Parameters:

matrix - An matrix of float.

Returns:

A new matrix of doubles.

toIntegerMatrix

public static final int[][] toIntegerMatrix(float[][] matrix)

Return a new matrix that is formed by converting the floats in the argument matrix to integers.

Parameters:

matrix - An matrix of float.

Returns:

A new matrix of integers.

toLongMatrix

public static final long[][] toLongMatrix(float[][] matrix)

Return a new matrix that is formed by converting the floats in the argument matrix to longs.

Parameters:

matrix - An matrix of float.

Returns:

A new matrix of longs.

toMatrixFromArray

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

Return a new matrix of floats 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 floats.

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

toString

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

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

toString

public static final java.lang.String toString(float[][] 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 float trace(float[][] 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.

transpose

public static final float[][] transpose(float[][] 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.

within

public static final boolean within(float[][] matrix1,
                                   float[][] matrix2,
                                   float distance)

Return true if the elements of the two matrices differ by no more than the specified distance. If distance is negative, return false.

Parameters:

matrix1 - The first matrix.

matrix2 - The second matrix.

distance - The distance to use for comparison.

Returns:

True if the elements of the two matrices are within the specified distance.

Throws:

java.lang.IllegalArgumentException - If the matrices do not have the same dimension. This is a run-time exception, so it need not be declared explicitly.

within

public static final boolean within(float[][] matrix1,
                                   float[][] matrix2,
                                   float[][] errorMatrix)

Return true if the elements of the two matrices differ by no more than the specified distances. If any element of errorMatrix is negative, return false.

Parameters:

matrix1 - The first matrix.

matrix2 - The second matrix.

errorMatrix - The distance to use for comparison.

Returns:

True if the elements of the two matrices are within the specified distance.

Throws:

java.lang.IllegalArgumentException - If the matrices do not have the same dimension. This is a run-time exception, so it need not be declared explicitly.

_checkSameDimension

protected static final void _checkSameDimension(java.lang.String caller,
                                                float[][] matrix1,
                                                float[][] 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 floats.

matrix2 - A matrix of floats.

_checkSquare

protected static final int _checkSquare(java.lang.String caller,
                                        float[][] 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 floats.

Returns:

The dimension of the square matrix.

_columns

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

Return the number of columns of a matrix.

_dimensionString

protected static final java.lang.String _dimensionString(float[][] 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.

_orthogonalizeRows

protected static final java.lang.Object[] _orthogonalizeRows(float[][] rowArrays)

Given a set of row vectors rowArrays[0] ... rowArrays[n-1], compute :

1. A new set of row vectors out[0] ... out[n-1] which are the orthogonalized versions of each input row vector. If a row vector rowArray[i] is a linear combination of the last 0 .. i - 1 row vectors, set array[i] to an array of 0's (array[i] being the 0 vector is a special case of this). Put the result in returnValue[0].
   
2. An n x n matrix containing the dot products of the input row vectors and the output row vectors, dotProductMatrix[j][i] = <rowArray[i], outArray[j]>. Put the result in returnValue[1].
   
3. An array containing 1 / (norm(outArray[i])²), with n entries. Put the result in returnValue[2].
   
4. A count of the number of rows that were found to be linear combinations of previous rows. Replace those rows with rows of zeros. The count is equal to the nullity of the transpose of the input matrix. Wrap the count with an Integer, and put it in returnValue[3].
   

Orthogonalization is done with the Gram-Schmidt process.

_rows

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

Return the number of rows of a matrix.

Parameters:

matrix - The matrix.

Returns:

The number of rows.