Package ptolemy.math

Class ComplexMatrixMath

java.lang.Object

ptolemy.math.ComplexMatrixMath

public class ComplexMatrixMath
extends java.lang.Object

This class provides a library for mathematical operations on matrices of complex numbers.

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:

Red (ctsay)

Pt.ProposedRating:

Yellow (ctsay)

Method Summary

Modifier and Type	Method	Description
protected static void	_checkSameDimension(java.lang.String caller, Complex[][] matrix1, Complex[][] matrix2)	Check that the two matrix arguments are of the same dimension.
protected static int	_checkSquare(java.lang.String caller, Complex[][] matrix)	Check that the argument matrix is a square matrix.
protected static int	_columns(Complex[][] matrix)	Return the number of columns of a matrix.
protected static java.lang.String	_dimensionString(Complex[][] matrix)	Print out the dimensions of the given matrix.
protected static java.lang.Object[]	_orthogonalizeRows(Complex[][] rowArrays)	Orthogonalize the rows of a matrix.
protected static int	_rows(Complex[][] matrix)	Return the number of rows of a matrix.
protected static Complex[][]	_zeroMatrix(Complex[][] matrix, int rows, int columns)	Place zeroes in specific places of the given matrix.
static Complex[][]	add(Complex[][] matrix, Complex z)	Return a new matrix that is constructed from the argument by adding the second argument to every element.
static Complex[][]	add(Complex[][] matrix1, Complex[][] matrix2)	Return a new matrix that is constructed from the argument by adding the second matrix to the first one.
static Complex[][]	allocCopy(Complex[][] matrix)	Return a new matrix that is a copy of the matrix argument.
static Complex[][]	applyBinaryOperation(ComplexBinaryOperation op, Complex[][] matrix, Complex z)	Return a new matrix that is formed by applying an instance of a ComplexBinaryOperation to each element in the input matrix, using z as the right argument in all cases and the matrix elements as the left arguments (op.operate(matrix[i][j], z)).
static Complex[][]	applyBinaryOperation(ComplexBinaryOperation op, Complex[][] matrix1, Complex[][] matrix2)	Return a new matrix that is formed by applying an instance of a ComplexBinaryOperation 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 Complex[][]	applyBinaryOperation(ComplexBinaryOperation op, Complex z, Complex[][] matrix)	Return a new matrix that is formed by applying an instance of a ComplexBinaryOperation to each element in the input matrix, using z as the left argument in all cases and the matrix elements as the right arguments (z, op.operate(matrix[i][j])).
static Complex[][]	applyUnaryOperation(ComplexUnaryOperation op, Complex[][] matrix)	Return a new matrix that is formed by applying an instance of a ComplexUnaryOperation to each element in the input matrix (op.operate(matrix[i][j])).
static Complex[][]	conjugate(Complex[][] matrix)	Return a new matrix that is constructed by conjugating the elements of the input matrix.
static Complex[][]	conjugateTranspose(Complex[][] matrix)	Return a new matrix that is constructed by transposing the input matrix and conjugating the elements.
static Complex[][]	crop(Complex[][] matrix, int rowStart, int colStart, int rowSpan, int colSpan)	Return a new matrix that is a sub-matrix of the input matrix argument.
static Complex	determinant(Complex[][] matrix)	Return the determinant of a square matrix.
static Complex[][]	diag(Complex[] 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 Complex[][]	divide(Complex[][] matrix, Complex z)	Return a new matrix that is constructed from the argument by dividing the second argument to every element.
static Complex[][]	divideElements(Complex[][] matrix1, Complex[][] matrix2)	Return a new matrix that is constructed by element-by-element division of the two matrix arguments.
static Complex[]	fromMatrixToArray(Complex[][] matrix)	Return a new array that is filled with the contents of the matrix.
static Complex[]	fromMatrixToArray(Complex[][] matrix, int maxRow, int maxCol)	Return a new array that is filled with the contents of the matrix.
static Complex[][]	identity(int dim)	Return an new identity matrix with the specified dimension.
static Complex[][]	identityMatrixComplex(int dim)	Return an new identity matrix with the specified dimension.
static double[][]	imagParts(Complex[][] matrix)	Return a new matrix that is formed by taking the imaginary parts of the complex numbers in the argument matrix.
static Complex[][]	inverse(Complex[][] A)	Return a new matrix that is constructed by inverting the input matrix.
static void	matrixCopy(Complex[][] srcMatrix, int srcRowStart, int srcColStart, Complex[][] 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 void	matrixCopy(Complex[][] srcMatrix, Complex[][] destMatrix)	Replace the first matrix argument elements with the values of the second matrix argument.
static Complex[][]	multiply(Complex[][] matrix, double scaleFactor)	Return a new matrix that is constructed by multiplying the matrix by a real scaleFactor.
static Complex[][]	multiply(Complex[][] matrix, Complex z)	Return a new matrix that is constructed by multiplying the matrix by a complex scaleFactor.
static Complex[]	multiply(Complex[][] matrix, Complex[] 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 Complex[][]	multiply(Complex[][] matrix1, Complex[][] matrix2)	Return a new matrix that is constructed from the argument by multiplying the first matrix by the second one.
static Complex[]	multiply(Complex[] array, Complex[][] 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 Complex[][]	multiplyElements(Complex[][] matrix1, Complex[][] matrix2)	Return a new matrix that is constructed by element by element multiplication of the two matrix arguments.
static Complex[][]	negative(Complex[][] matrix)	Return a new matrix that is the additive inverse of the argument matrix.
static Complex[][]	orthogonalizeColumns(Complex[][] matrix)	Return a new matrix that is formed by orthogonalizing the columns of the input matrix (the column vectors are orthogonal).
static Complex[][]	orthogonalizeRows(Complex[][] matrix)	Return a new matrix that is formed by orthogonalizing the rows of the input matrix (the row vectors are orthogonal).
static Complex[][]	orthonormalizeColumns(Complex[][] matrix)	Return a new matrix that is formed by orthonormalizing the columns of the input matrix (the column vectors are orthogonal and have norm 1).
static Complex[][]	orthonormalizeRows(Complex[][] 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 double[][]	realParts(Complex[][] matrix)	Return a new matrix that is formed by taking the real parts of the complex numbers in the argument matrix.
static Complex[][]	subtract(Complex[][] matrix1, Complex[][] matrix2)	Return a new matrix that is constructed from the argument by subtracting the second matrix from the first one.
static Complex	sum(Complex[][] matrix)	Return the sum of the elements of a matrix.
static Complex[][]	toMatrixFromArray(Complex[] array, int rows, int cols)	Return a new matrix of complex numbers that is initialized from a 1-D array.
static java.lang.String	toString(Complex[][] matrix)	Return a new String representing the matrix, formatted as in Java array initializers.
static java.lang.String	toString(Complex[][] 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 Complex	trace(Complex[][] matrix)	Return the trace of a square matrix, which is the sum of the diagonal entries A11 + A22 + ...
static Complex[][]	transpose(Complex[][] matrix)	Return a new matrix that is constructed by transposing the input matrix.
static boolean	within(Complex[][] matrix1, Complex[][] matrix2, double maxError)	Return true if all the distances between corresponding elements in matrix1 and matrix2 are all less than or equal to the magnitude of maxError.
static boolean	within(Complex[][] matrix1, Complex[][] matrix2, double[][] maxError)	Return true if all the distances between corresponding elements in matrix1 and matrix2 are all less than or equal to corresponding elements in maxError.
static boolean	within(Complex[][] matrix1, Complex[][] matrix2, Complex maxError)	Return true if all the distances between corresponding elements in matrix1 and matrix2 are all less than or equal to the magnitude of maxError.
static boolean	within(Complex[][] matrix1, Complex[][] matrix2, Complex[][] maxError)	Return true if all the distances between corresponding elements in matrix1 and matrix2 are all less than or equal to the magnitude of the corresponding element in maxError.
static Complex[][]	zero(int rows, int columns)	Return a new complex matrix whose entries are all zero.

Methods inherited from class java.lang.Object

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

Method Detail

add

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

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

Parameters:

matrix - A matrix of complex numbers.

z - The complex number to add.

Returns:

A new matrix of complex numbers formed by adding z to every element of matrix.

add

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

Return a new matrix that is constructed from the argument by adding the second matrix to the first one.

Parameters:

matrix1 - The first matrix of complex numbers.

matrix2 - The second matrix of complex numbers.

Returns:

A new matrix of complex numbers formed by adding matrix2 to matrix1.

Throws:

java.lang.IllegalArgumentException - If the matrices do not have the same dimensions.

allocCopy

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

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

Parameters:

matrix - A matrix of complex numbers.

Returns:

A new matrix of complex numbers that is a copy of matrix.

applyBinaryOperation

public static final Complex[][] applyBinaryOperation(ComplexBinaryOperation op,
                                                     Complex z,
                                                     Complex[][] matrix)

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

Parameters:

op - A complex binary operation.

z - A complex number.

matrix - A matrix of complex numbers.

Returns:

A new matrix formed by applying (z, op.operate(matrix[i][j])) to each element of matrix.

applyBinaryOperation

public static final Complex[][] applyBinaryOperation(ComplexBinaryOperation op,
                                                     Complex[][] matrix,
                                                     Complex z)

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

Parameters:

op - A complex binary operation.

z - A complex number.

matrix - A matrix of complex numbers.

Returns:

A new matrix formed by applying (op.operate(matrix[i][j], z)) to each element of matrix.

applyBinaryOperation

public static final Complex[][] applyBinaryOperation(ComplexBinaryOperation op,
                                                     Complex[][] matrix1,
                                                     Complex[][] matrix2)

Return a new matrix that is formed by applying an instance of a ComplexBinaryOperation 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])).

Parameters:

op - A complex binary operation.

matrix1 - The first matrix of complex numbers.

matrix2 - The second matrix of complex numbers.

Returns:

A new matrix of complex numbers with each element equal to (op.operate(matrix1[i][j], matrix2[i][j])).

Throws:

java.lang.IllegalArgumentException - If the matrices do not have the same dimensions.

applyUnaryOperation

public static final Complex[][] applyUnaryOperation(ComplexUnaryOperation op,
                                                    Complex[][] matrix)

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

Parameters:

op - A complex unary operation.

matrix - The matrix of complex numbers.

Returns:

A new matrix of complex numbers with each element equal to (op.operate(matrix1[i][j])).

conjugate

public static final Complex[][] conjugate(Complex[][] matrix)

Return a new matrix that is constructed by conjugating the elements of the input matrix.

Parameters:

matrix - The matrix of complex numbers.

Returns:

A new matrix of complex numbers formed by conjugating the elements of matrix.

conjugateTranspose

public static final Complex[][] conjugateTranspose(Complex[][] matrix)

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

Parameters:

matrix - The matrix of complex numbers.

Returns:

A new matrix of complex numbers formed by transposing the input matrix and conjugating the elements.

crop

public static final Complex[][] crop(Complex[][] 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 complex numbers.

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.

Returns:

A new matrix that is a sub-matrix of matrix.

determinant

public static final Complex determinant(Complex[][] 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].

Parameters:

matrix - The matrix for which to calculate the determinant.

Returns:

The determinant of the matrix.

diag

public static final Complex[][] diag(Complex[] 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.

Parameters:

array - The input array of complex numbers.

Returns:

A new matrix containing array as its diagonal.

divide

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

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

Parameters:

matrix - A matrix of complex numbers.

z - The complex number to divide.

Returns:

A new matrix of complex numbers.

divideElements

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

Parameters:

matrix1 - The first matrix of complex numbers.

matrix2 - The second matrix of complex numbers.

Returns:

A new matrix of complex numbers constructed by element-by-element division of the two matrix arguments.

Throws:

java.lang.IllegalArgumentException - If the matrices do not have the same dimensions.

fromMatrixToArray

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

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

Returns:

A new array of complex numbers filled with the contents of the matrix.

fromMatrixToArray

public static final Complex[] fromMatrixToArray(Complex[][] 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 complex numbers 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 complex numbers.

maxRow - The maximum number of rows.

maxCol - The maximum number of columns.

Returns:

A new array of complex numbers filled with the contents of the matrix.

identity

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

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

Parameters:

dim - An integer representing the dimension of the identity matrix to be returned.

Returns:

A new identity matrix of complex numbers with the specified dimension.

identityMatrixComplex

public static final Complex[][] identityMatrixComplex(int dim)

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

Parameters:

dim - An integer representing the dimension of the identity matrix to be returned.

Returns:

A new identity matrix of complex numbers with the specified dimension.

imagParts

public static final double[][] imagParts(Complex[][] matrix)

Return a new matrix that is formed by taking the imaginary parts of the complex numbers in the argument matrix.

Parameters:

matrix - A matrix of complex numbers.

Returns:

A new matrix of doubles from the imaginary parts of matrix.

inverse

public static final Complex[][] inverse(Complex[][] 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]

Parameters:

A - A matrix of complex numbers.

Returns:

the inverse of matrix.

matrixCopy

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

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

Parameters:

destMatrix - A matrix of complex numbers, used as the destination.

srcMatrix - A matrix of complex numbers, used as the source.

matrixCopy

public static final void matrixCopy(Complex[][] srcMatrix,
                                    int srcRowStart,
                                    int srcColStart,
                                    Complex[][] 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 complex numbers, 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 complex numbers, 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 Complex[][] multiply(Complex[][] matrix,
                                         double scaleFactor)

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

Parameters:

matrix - A matrix of complex numbers.

scaleFactor - A double used to multiply each element of the matrix by.

Returns:

A new matrix that is formed by multiplying the matrix by scaleFactor.

multiply

public static final Complex[][] multiply(Complex[][] matrix,
                                         Complex z)

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

Parameters:

matrix - A matrix of complex numbers.

z - A complex number used to multiply each element of the matrix by.

Returns:

A new matrix that is formed by multiplying the matrix by z.

multiply

public static final Complex[] multiply(Complex[][] matrix,
                                       Complex[] 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.

Parameters:

matrix - A matrix of complex numbers.

array - An array of complex numbers.

Returns:

A new matrix that is formed by multiplying array by matrix.

multiply

public static final Complex[] multiply(Complex[] array,
                                       Complex[][] 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.

Parameters:

array - An array of complex numbers.

matrix - A matrix of complex numbers.

Returns:

A new matrix that is formed by multiplying matrix by array.

multiply

public static final Complex[][] multiply(Complex[][] matrix1,
                                         Complex[][] 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 complex numbers.

matrix2 - The second matrix of complex numbers.

Returns:

A new matrix of complex numbers equal to matrix1 times matrix2.

See Also:

multiplyElements(Complex[][], Complex[][])

multiplyElements

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

Parameters:

matrix1 - The first matrix of complex numbers.

matrix2 - The second matrix of complex numbers.

Returns:

A new matrix constructed by element by element multiplication of the two matrix arguments.

negative

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

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

Parameters:

matrix - A matrix of complex numbers.

Returns:

A new matrix of complex numbers, which is the additive inverse of the given matrix.

orthogonalizeColumns

public static final Complex[][] orthogonalizeColumns(Complex[][] 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.

Parameters:

matrix - A matrix of complex numbers.

Returns:

A new matrix formed by orthogonalizing the columns of the input matrix.

orthogonalizeRows

public static final Complex[][] orthogonalizeRows(Complex[][] 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.

Parameters:

matrix - A matrix of complex numbers.

Returns:

A new matrix formed by orthogonalizing the rows of the input matrix.

orthonormalizeColumns

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

Return a new matrix that is formed by orthonormalizing 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.

Parameters:

matrix - A matrix of complex numbers.

Returns:

A new matrix formed by orthonormalizing the columns of the input matrix.

orthonormalizeRows

public static final Complex[][] orthonormalizeRows(Complex[][] 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.

Parameters:

matrix - A matrix of complex numbers.

Returns:

A new matrix formed by orthonormalizing the rows of the input matrix.

realParts

public static final double[][] realParts(Complex[][] matrix)

Return a new matrix that is formed by taking the real parts of the complex numbers in the argument matrix.

Parameters:

matrix - An matrix of complex numbers.

Returns:

A new matrix of the double coefficients of the complex numbers of matrix.

subtract

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

Return a new matrix that is constructed from the argument by subtracting the second matrix from the first one.

Parameters:

matrix1 - The first matrix of complex numbers.

matrix2 - The second matrix of complex numbers.

Returns:

A new matrix of complex numbers constructed by subtracting the second matrix from the first one.

Throws:

java.lang.IllegalArgumentException - If the matrices do not have the same dimensions.

sum

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

Return the sum of the elements of a matrix.

Parameters:

matrix - The matrix.

Returns:

The sum of the elements of the matrix.

toMatrixFromArray

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

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

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 complex numbers initialized from a 1-D array.

toString

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

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

Parameters:

matrix - A matrix of Complex numbers.

Returns:

A new String representing the matrix in Java array initializers.

toString

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

Parameters:

matrix - A matrix of Complex numbers.

elementDelimiter - The delimiter between elements, typically ", ".

matrixBegin - The start of the matrix, typically "{".

matrixEnd - The end of the matrix, typically "{".

vectorBegin - The start of the vector, typically "{".

vectorDelimiter - The delimiter between elements, typically ", ".

vectorEnd - The end of the vector, typically "}".

Returns:

A new String representing the matrix in the specified format.

trace

public static final Complex trace(Complex[][] 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 matrix of complex numbers.

Returns:

A complex number which is the trace of matrix.

transpose

public static final Complex[][] transpose(Complex[][] 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. Note that for complex matrices, the conjugate transpose is more commonly used.

Parameters:

matrix - A matrix of complex numbers.

Returns:

A new matrix of complex numbers which is the transpose of matrix.

within

public static final boolean within(Complex[][] matrix1,
                                   Complex[][] matrix2,
                                   Complex maxError)

Return true if all the distances between corresponding elements in matrix1 and matrix2 are all less than or equal to the magnitude of maxError. If both matrices are empty, return true.

Parameters:

matrix1 - The first matrix.

matrix2 - The second matrix.

maxError - A complex number whose magnitude is taken to be the distance threshold.

Returns:

True or false.

Throws:

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

within

public static final boolean within(Complex[][] matrix1,
                                   Complex[][] matrix2,
                                   double maxError)

Return true if all the distances between corresponding elements in matrix1 and matrix2 are all less than or equal to the magnitude of maxError. If both matrices are empty, return true. If maxError is negative, return false.

Parameters:

matrix1 - The first matrix.

matrix2 - The second matrix.

maxError - The threshold for the magnitude of the difference.

Returns:

True or false.

Throws:

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

within

public static final boolean within(Complex[][] matrix1,
                                   Complex[][] matrix2,
                                   double[][] maxError)

Return true if all the distances between corresponding elements in matrix1 and matrix2 are all less than or equal to corresponding elements in maxError. If both matrices are empty, return true. If any element of maxError is negative, return false.

Parameters:

matrix1 - The first matrix.

matrix2 - The second matrix.

maxError - The matrix of thresholds for the magnitudes of difference.

Returns:

True or false.

Throws:

java.lang.IllegalArgumentException - If the matrices do not have the same dimensions.

within

public static final boolean within(Complex[][] matrix1,
                                   Complex[][] matrix2,
                                   Complex[][] maxError)

Return true if all the distances between corresponding elements in matrix1 and matrix2 are all less than or equal to the magnitude of the corresponding element in maxError. If both matrices are empty, return true.

Note that there is no notion of negative distance with complex numbers, so unlike the within() methods for other types, this method will not return false if an element of the maxError matrix is negative.

Parameters:

matrix1 - The first matrix.

matrix2 - The second matrix.

maxError - A matrix of complex numbers whose magnitudes for each element are taken to be the distance thresholds.

Returns:

True or false.

Throws:

java.lang.IllegalArgumentException - If the arrays are not of the same length.

zero

public static final Complex[][] zero(int rows,
                                     int columns)

Return a new complex matrix whose entries are all zero. The size of the matrix is specified by the input arguments.

Parameters:

rows - The number of rows of the zero matrix.

columns - The number of columns of the zero matrix.

Returns:

A new complex matrix whose entries are all zero.

_checkSameDimension

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

matrix2 - A matrix of complex numbers.

_checkSquare

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

Returns:

The dimension of the square matrix (an int).

_columns

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

Return the number of columns of a matrix.

Parameters:

matrix - A matrix of complex numbers.

Returns:

The number of columns of the given matrix.

_dimensionString

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

Print out the dimensions of the given matrix.

Parameters:

matrix - A matrix of complex numbers.

Returns:

A string specifying the dimensions of the given matrix.

_orthogonalizeRows

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

Orthogonalize the rows of a matrix. 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.

Parameters:

rowArrays - A set of row vectors.

Returns:

An array of four objects, where the first is the orthogonal matrix, the second is a matrix containing the dot products of the input rows with the output rows, the third is an array of the reciprocals of the norms squared of the orthogonal rows, and the fourth is an Integer containing the number of linearly independent rows in the argument matrix.

_rows

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

Return the number of rows of a matrix.

Parameters:

matrix - A matrix of complex numbers.

Returns:

The number of rows of the given matrix.

_zeroMatrix

protected static final Complex[][] _zeroMatrix(Complex[][] matrix,
                                               int rows,
                                               int columns)

Place zeroes in specific places of the given matrix.

Parameters:

matrix - A matrix of complex numbers.

rows - The number of rows for the matrix.

columns - The number of columns for the matrix.

Returns:

The modified matrix with zeroes in the desired positions.