Michael Thomas Flanagan's Java Scientific LibraryComplexMatrix Class:     Complex Matrices

Last update: 17 July 2011

This class defines an object that represents a complex matrix. The instance variables are:
• a rectangular two dimensional array of complex numbers (Complex[][] matrix)
• the number of rows (nrow)
• the number of columns (ncol)
• a permutation array of integers to store row interchange indices during matrix manipulations (int[] index)
• a double to store whether the number of row interchanges during matrix manipulations is odd or even (double dswap)
It includes the methods needed for complex matrix manipulations and for the solution of a set of complex linear equations.
The Complex constructor and the basic complex number methods may found in the Complex class.

import directive: import flanagan.complex.ComplexMatrix; Related classes

### SUMMARY OF CONSTRUCTORS AND METHODS

 Constructors public ComplexMatrix(int nrow, int ncol) public ComplexMatrix(int nrow, int ncol, Complex const) public ComplexMatrix(Complex[][] twoD) public ComplexMatrix(double [][] twoD) public ComplexMatrix(Matrix matrix) public ComplexMatrix(ComplexMatrix matrix) Create SpecialMatrices public static ComplexMatrix identityMatrix(int nrow) public static ComplexMatrix scalarMatrix(int nrow, Complex diagconst) public static ComplexMatrix diagonalMatrix(int nrow, Complex[] diag) Row Matrix public static ComplexMatrix rowMatrix(Complex[] oneDarray) Column Matrix public static ComplexMatrix columnMatrix(Complex[] oneDarray) Set values public setTwoDarray(Complex[][] twoD) public setTwoDarray(double[][] twoD) public setElement(int i, int j, Complex aa) public setElement(int i, int j, double real, double imag) public setSubMatrix(int i, int j, Complex[][] submat) public setSubMatrix(int i, int j, int k, int l, Complex[][] submat) public setSubMatrix(int[] row, int[] col, Complex[][] submat) Get values public int getNrow() public int getNcol() public Complex[][] getArrayReference() public Complex[][] getArrayCopy() public Complex getElementReference(int i, int j) public Complex getElementCopy(int i, int j) public ComplexMatrix getSubMatrix(int i, int j, int k, int l) public ComplexMatrix getSubMatrix(int[] row, int[] col) public int[] getIndexReference() public int[] getIndexCopy() public double getSwap() Deep Copy public ComplexMatrix copy() public Object clone() public static ComplexMatrix copy(ComplexMatrix aa) Conversions public static ComplexMatrix toComplexRowMatrix(Complex[] oneDarray) public static ComplexMatrix toComplexRowMatrix(double[] oneDarray) public static ComplexMatrix toComplexColumnMatrix(Complex[] oneDarray) public static ComplexMatrix toComplexColumnMatrix(double[] oneDarray) public static ComplexMatrix toComplexMatrix(Matrix marray) public static ComplexMatrix toComplexMatrix(double[][] darray) Addition public ComplexMatrix plus(ComplexMatrix bb) public ComplexMatrix plus(Complex[][] bb) public ComplexMatrix plus(Matrix bb) public ComplexMatrix plus(double[][] bb) public static ComplexMatrix plus(ComplexMatrix aa, ComplexMatrix bb) public void plusEquals(ComplexMatrix bb) Subtraction public ComplexMatrix minus(ComplexMatrix bb) public ComplexMatrix minus(Complex[][] bb) public ComplexMatrix minus(Matrix bb) public ComplexMatrix minus(double[][] bb) public static ComplexMatrix minus(ComplexMatrix aa, ComplexMatrix bb) public void minusEquals(ComplexMatrix bb) Multiplication public ComplexMatrix times(ComplexMatrix bb) public ComplexMatrix times(Complex bb) public ComplexMatrix times(Complex[][] bb) public ComplexMatrix times(Matrix bb) public ComplexMatrix times(double[][] bb) public ComplexMatrix times(double bb) public static ComplexMatrix times(ComplexMatrix aa, ComplexMatrix bb) public static ComplexMatrix times(ComplexMatrix aa, Complex bb) public static ComplexMatrix times(ComplexMatrix aa, double bb) public void timesEquals(ComplexMatrix bb) public void timesEquals(Complex bb) public void timesEquals(double bb) Division public ComplexMatrix over(ComplexMatrix bb) public ComplexMatrix over(Complex[][] bb) public ComplexMatrix over(Matrix bb) public ComplexMatrix over(double[][] bb) public static ComplexMatrix over(ComplexMatrix aa, ComplexMatrix bb) public void overEquals(ComplexMatrix bb) Inverse public ComplexMatrix inverse() public static ComplexMatrix inverse(ComplexMatrix aa) Transpose public ComplexMatrix transpose() public static ComplexMatrix transpose(ComplexMatrix aa) Conjugate public ComplexMatrix conjugate() public static ComplexMatrix conjugate(ComplexMatrix aa) Adjoin public ComplexMatrix adjoin() public static ComplexMatrix adjoin(ComplexMatrix aa) Opposite public ComplexMatrix opposite() public static ComplexMatrix opposite(ComplexMatrix aa) Reduced Row Echelon Form public ComplexMatrix reducedRowEchelonForm() Trace public Complex trace() public static Complex trace(ComplexMatrix aa) Determinant public Complex determinant() public static Complex determinant(ComplexMatrix aa) public Complex logDeterminant() public static Complex logDeterminant(ComplexMatrix aa) Cofactor public ComplexMatrix cofactor() public Complex cofactor(int i, int j) Norms public double frobeniusNorm () public double oneNorm () public double infinityNorm () LU Decompostion public ComplexMatrix luDecomp() public Complex luBackSub(Complex[] bvec) Linear EquationSet public Complex[] solveLinearSet(Complex[]bvec)

### CONSTRUCTORS

public ComplexMatrix(int nrow, int ncol)
Usage:                      ComplexMatrix aa = new ComplexMatrix(nrow, ncol);
This creates a new instance of ComplexMatrix, aa, with a a nrow x ncol matrix of complex variables and initialises all the real parts (real) and the imaginary parts (imag) to zero.

public ComplexMatrix(int nrow, int ncol, Complex const)
Usage:                      ComplexMatrix aa = new ComplexMatrix(nrow, ncol, const);
This creates a new instance of ComplexMatrix, aa, with a a nrow x ncol matrix of complex variables and initialises all the matrix elements to the complex number const.

public ComplexMatrix(Complex[][] twoD)
public ComplexMatrix(double[][] twoD)
Usage:                      ComplexMatrix aa = new ComplexMatrix(twoD);
This creates a new instance of ComplexMatrix, aa, with a matrix that is a deep copy of the two dimensional array, twoD, of complex (Complex) or real (double) numbers.

public ComplexMatrix(ComplexMatrix bb)
public ComplexMatrix(Matrix bb)
Usage:                      ComplexMatrix aa = new ComplexMatrix(bb);
This creates a new instance of ComplexMatrix, aa, with a complex matrix that is a s a deep copy of the matrix in the existing Complex Matrix instance or Matrix instance, bb.

### PUBLIC METHODS

CREATE SPECIAL MATRICES
public static ComplexMatrix identityMatrix(int nrow)
Usage:                      aa = ComplexMatrix.identityMatrix(n);
Creates an n x n complex identity matrix (unit matrix) [all diagonal elements = 1+j0, all off-diagonal elements = 0+j0].

public static ComplexMatrix scalarMatrix(int nrow, Complex diagconst)
Usage:                      aa = ComplexMatrix.scalarMatrix(n, diagconst);
Creates an n x n complex scalar matrix [all diagonal elements = the same complex number (diagconst), all off-diagonal elements = 0+j0].

public static ComplexMatrix diagonalMatrix(int nrow, Complex[] diag)
Usage:                      aa = ComplexMatrix.diagonalMatrix(n, diag);
Creates an n x n complex diagonal matrix with the diagonal elements = the complex array, diag, and all off-diagonal elements = 0+j0.

ROW MATRIX
public static ComplexMatrix rowMatrix(Complex[] oneDarray)
Usage:                      aa = ComplexMatrix.rowMatrix(oneDarray);
Converts a one dimensional array, oneDarray of Complex into a row matrix of the type ComplexMatrix.

COLUMN MATRIX
public static ComplexMatrix columnMatrix(Complex[] oneDarray)
Usage:                      aa = ComplexMatrix.columnMatrix(oneDarray);
Converts a one dimensional array, oneDarray of Complex into a column matrix of the type ComplexMatrix.

SET VALUES
public setTwoDarray(Complex[][] twoD)
public setTwoDarray(double[][] twoD)
Usage:                      aa.setTwoDarrayl(dd);
Sets the matrix of aa with a deep copy of an existing nrow x ncol 2-D matrix of complex or double variables, dd.

public setElement(int i, int j, Complex aa)
public setElement(int i, int j, double real, double imag)
Usage:                      aa.setElement(i, j, cc);
Sets the internal 2D array element, of matrix of aa, matrix[i][j], to a copy of the value of the Complex() bb.
Usage:                      aa.setElement(i, j, x, y);
Sets the real part of the internal 2D array element, of matrix of aa, matrix[i][j].real to x and the imaginary part matrix[i][j].imag to y.

public setSubMatrix(int i, int j, Complex[][] submat)
Usage:                      aa.setSubmatrix(i, j, submat);
Sets a sub-matrix starting with column index i, row index j to a copy of the 2D complex array submat.

public setSubMatrix(int i, int j, int k, int l, Complex[][] submat)
Usage:                      aa.setSubmatrix(i, j, k, l, submat);
Sets a sub-matrix starting with column index i, row index j and ending with column index k, row index l to a copy of the 2D complex array submat. Method above does the same more conveniently. This method retained for backward compatibity.

public setSubMatrix(int[] row, int[] col, Complex[][] submat)
Usage:                      aa.setSubMatrix(row, col, submat);
Sets a sub-matrix defined by an array of row indices, row, and an array of column indices, col, to a copy of the 2D complex array submat

GET VALUES
public int getNrow()
Usage:                      nrow = aa.getNrow();
Returns the number of rows.

public int getNcol()
Usage:                      ncol = aa.getNcol();
Returns the number of columns.

public Complex[][] getArrayReference()
Usage:                      xx = aa.getArrayReference();
Returns a reference (pointer) to the internal 2D array, matrix.

public Complex[][] getArrayCopy()
Usage:                      xx = aa.getArrayReference();
Returns a copy of the internal 2D array, matrix.

public Complex getElementReference(int i, int j)
Usage:                      xx = aa.getElementReference();
Returns a reference (pointer) to the internal 2D array element, matrix[i][j].

public Complex getElementCopy(int i, int j)
Usage:                      xx = aa.getElementCopy();
Returns a copy of the internal 2D array element, matrix[i][j].

public ComplexMatrix getSubMatrix(int i, int j, int k, int l)
public ComplexMatrix getSubMatrix(int[] row, int[] col)
Usage:                      xx = aa.getSubMatrix(i, j, k, l);
Return a copy of the sub-matrix starting with row index i, column index j and ending with row index k, column index l.
Usage:                      xx = aa.getSubMatrix(row, col);
Return a copy of the sub-matrix defined by the array of row indices, row, and the array of column indices, col.

public int[] getIndexReference()
Usage:                      xx = aa.getIndexReference();
Returns a reference (pointer) to the internal permutation array index.

public int[] getIndexCopy()
Usage:                      xx = aa.getIndexCopy();
Returns a copy of the internal permutation array index.

public int[] getSwap()
Usage:                      x = aa.getSwap();
Returns the odd/even swap index, swap.

COPY ComplexMatrix
public ComplexMatrix copy()
public Object clone()
public static ComplexMatrix copy(ComplexMatrix aa)
Usage:                      bb = aa.copy();
Usage:                      bb = ComplexMatrix.copy(aa);
A deep copy of the ComplexMatrix instance, aa, is returned.

Clone ComplexMatrix
Usage:                      bb = (ComplexMatrix) aa.clone();
A deep copy of the ComplexMatrix instance, aa, is returned. This method overrides java.lang.Object.clone().

CONVERSIONS
Row Matrices
public static ComplexMatrix toComplexRowMatrix(Complex[] oneDarray)
public static ComplexMatrix toComplexRowMatrix(double[] oneDarray)
Usage:                      ComplexMatrix aa = ComplexMatrix.toComplexRowMatrix(oneDarray);
Converts a one dimensional array into a row matrix of the type ComplexMatrix. The argument, oneDarray, may be a 1-D array of Complex or doubles.

Column Matrices
public static ComplexMatrix toComplexColumnMatrix(Complex[] oneDarray)
public static ComplexMatrix toComplexColumnMatrix(double[] oneDarray)
Usage:                      ComplexMatrix aa = ComplexMatrix.toComplexColumnMatrix(oneDarray);
Converts a one dimensional array into a column matrix of the type ComplexMatrix. The argument, oneDarray, may be a 1-D array of Complex or doubles.

Real Matrix to Complex Matrix
public static ComplexMatrix toComplexMatrix(Matrix marray)
public static ComplexMatrix toComplexMatrix(double[][] darray)
Usage:                      ComplexMatrix aa = ComplexMatrix.toComplexMatrix(bb);
Converts the argument bb to a ComplexMatrix. The argument, bb, may be Matrix or a 2-D array of doubles.

public ComplexMatrix plus(ComplexMatrix bb)
public ComplexMatrix plus(Complex[][] bb)
public ComplexMatrix plus(Matrix bb)
public ComplexMatrix plus(double[][] bb)
Usage:                      cc = aa.plus(bb);
Performs the operation cc = aa + bb where aa and cc are ComplexMatrix and bb may be ComplexMatrix, a real Matrix, a 2-D Complex array or a 2-D array of doubles.

public static ComplexMatrix plus(ComplexMatrix aa, ComplexMatrix bb)
Usage:                      cc = ComplexMatrix.plus(aa, bb);
Performs the operation cc = aa + bb where aa, bb and cc are all ComplexMatrix.

Equivalence of the += operator
public void plusEquals(ComplexMatrix bb)
Usage:                      aa.plusEquals(bb);
Performs the operation aa = aa + bb where aa and bb are ComplexMatrix.

SUBTRACTION
public ComplexMatrix minus(ComplexMatrix bb)
public ComplexMatrix minus(Complex[][] bb)
public ComplexMatrix minus(Matrix bb)
public ComplexMatrix minus(double[][] bb)
Usage:                      cc = aa.minus(bb);
Performs the operation cc = aa - bb where aa and cc are ComplexMatrix and bb may be ComplexMatrix, a real Matrix, a 2-D Complex array or a 2-D array of doubles.

public static ComplexMatrix minus(ComplexMatrix aa, ComplexMatrix bb)
Usage:                      cc = ComplexMatrix.minus(aa, bb);
Performs the operation cc = aa - bb where aa, bb and cc are all ComplexMatrix.

Equivalence of the −= operator
public void plusEquals(ComplexMatrix bb)
Usage:                      aa.minusEquals(bb);
Performs the operation aa = aa - bb where aa and bb are ComplexMatrix.

MULTIPLICATION
public ComplexMatrix times(ComplexMatrix bb)
public ComplexMatrix times(Complex[][] bb)
public ComplexMatrix times(Matrix bb)
public ComplexMatrix times(double[][] bb)
public ComplexMatrix times(Complex bb)
public ComplexMatrix times(double bb)
Usage:                      cc = aa.times(bb);
Performs the operation cc = aa *bb where aa and cc are ComplexMatrix and bb is ComplexMatrix, a real Matrix, a 2-D Complex array, a 2-D array of doubles, Complex or double (i.e. real).

public static ComplexMatrix times(ComplexMatrix aa, ComplexMatrix bb)
public static ComplexMatrix times(ComplexMatrix aa, Complex bb)
public static ComplexMatrix times(ComplexMatrix aa, double bb)
Usage:                      cc = ComplexMatrix.times(aa, bb);
Performs the operation cc = aa *bb where aa and cc are ComplexMatrix and bb may be ComplexMatrix, Complex or double (i.e. real).

Equivalence of the *= operator
public void timesEquals(ComplexMatrix bb)
public void timesEquals(Complex bb)
public void timesEquals(double bb)
Usage:                      cc = aa.timesEquals(bb);
Performs the operation aa = aa *bb where aa and cc are ComplexMatrix and bb is ComplexMatrix, Complex or double (i.e. real).

DIVISION
public ComplexMatrix over(ComplexMatrix bb)
public ComplexMatrix over(Complex[][] bb)
public ComplexMatrix over(Matrix bb)
public ComplexMatrix over(double[][] bb)
Usage:                      cc = aa.over(bb);
Performs the operation cc = aa/bb where aa and cc are ComplexMatrix and bb may be ComplexMatrix, a real Matrix, a 2-D Complex array or a 2-D array of doubles. This method first converts bb to a ComplexMatrix and returns the product of the ComplexMatrix aa and the inverse of the ComplexMatrix transform of bb.

public static ComplexMatrix over(ComplexMatrix aa, ComplexMatrix bb)
Usage:                      cc = ComplexMatrix.over(aa, bb);
Performs the operation cc = aa/bb where aa, bb and cc are all ComplexMatrix. This method first converts bb to a ComplexMatrix and returns the product of the ComplexMatrix aa and the inverse of the ComplexMatrix transform of bb.

Equivalence of the /= operator
public void overEquals(ComplexMatrix bb)
Usage:                      aa.plusEquals(bb);
Performs the operation aa = aa/bb where aa and bb are ComplexMatrix. This method first converts bb to a ComplexMatrix and returns the product of the ComplexMatrix aa and the inverse of the ComplexMatrix transform of bb.

INVERSE
public ComplexMatrix inverse()
public static ComplexMatrix inverse(ComplexMatrix aa)
Usage:                      bb = aa.inverse();
Usage:                      bb = ComplexMatrix.inverse(aa);
Returns the inverse of a complex square matrix, aa.

TRANSPOSE
public ComplexMatrix transpose()
public static ComplexMatrix transpose(ComplexMatrix aa)
Usage:                      bb = aa.transpose();
Usage:                      bb = ComplexMatrix.transpose(aa);
Returns the transpose of a complex square matrix, aa.

CONJUGATE
public ComplexMatrix conjugatr()
public static ComplexMatrix conjugate(ComplexMatrix aa)
Usage:                      bb = aa.conjugate();
Usage:                      bb = ComplexMatrix.conjugate(aa);
Returns the complex conjugate matrix of a complex matrix, aa.

Returns the adjoin of a complex matrix, aa.

OPPOSITE
public ComplexMatrix opposite()
public static ComplexMatrix opposite(ComplexMatrix aa)
Usage:                      bb = aa.opposite();
Usage:                      bb = ComplexMatrix.opposite(aa);
Returns the opposite of a complex matrix, aa.

REDUCED ROW ECHELON FORM
public ComplexMatrix reducedRowEchelonForm()
Usage:                      rref = aa.reducedRowEchelonForm();
This method calculates and returns the equivalent reduced row echelon form.

LU DECOMPOSITION
public ComplexMatrix luDecomp()
Usage:                      lu = aa.luDecomp();
Returns the complex LU decomposition of a complex matrix, aa.
See Numerical Recipes, The Art of Scientific Computing by W H Press, S A Teukolsky, W T Vetterling & B P Flannery, Cambridge University Press, http://www.nr.com/, for details of the LU decomposition. This method mimics their C language function for real numbers.
int[] index stores of row permutations.
double dswap is assigned +1.0 for even number of row interchanges or -1.0 for odd number of row interchanges.

public Complex luBackSub(Complex[] bvec)
Usage:                      xx = lu.luDecomp(bb);
The forward and backward substitution procedure associated with the complex LU decompostion when used to solves the linear set of complex equations A.x = b. luBackSub actually solves L.x = b where L is the complex LU decompostion of A (lu above) obtained from luDecomp(), b is bb above and x is bb above. See solveLinearSet() for its use in solving the equations A.x = b.

SOLUTION OF A SET OF LINEAR EQUATIONS
public Complex solveLinearSet(Complex[] b)
Usage:                      x = a.solveLinearSet(b);
Solves the linear set of complex equations A.x = b where A is the matrix of complex coefficients, b is the right-hand side complex vector and x is the complex vector of solution values. This method uses an LU decomposition [luDecomp() and luBackSub() - see above].

TRACE
public Complex trace()
public static Complex trace(ComplexMatrix aa)
Usage:                      b = aa.trace();
Usage:                      b = ComplexMatrix.trace(aa);
Returns the trace of a complex matrix, aa.

DETERMINANT
public Complex determinant()
public static Complex determinant(ComplexMatrix aa)
Usage:                      b = aa.determinant();
Usage:                      b = ComplexMatrix.determinant(aa);
Returns the determinant of a complex square matrix, aa.

public Complex logDeterminant()
public static Complex logDeterminant(ComplexMatrix aa)
Usage:                      b = aa.logDeterminant();
Usage:                      b = ComplexMatrix.logDeterminant(aa);
Returns the natural logarithm of the determinant of a complex square matrix, aa. Useful if determinant() underflows or overflows.

COFACTOR
public Complex cofactor(int i, int j)
public ComplexMatrix cofactor()
Usage:                      cofactor = aa.cofactor(i,j);
Returns the cofactor (algebraic complement), αij, for the ith row and the jth column of the matrix A,

where |Aij| is the determinant of the submatrix, Aij, of the matrix, A, obtained by deleting the ith row and jth column from the matrix, A. The matrix, A, is the matrix embodied in the instance, aa, in the above usage.

Usage:                      cofactorMatrix = aa.cofactor();
Returns the Matrix of all cofactors for the Matrix embedded in aa (see immediately above for the definition of a cofactor).

NORMS
public double frobeniusNorm ()
Usage:                      b = aa.frobeniusNorm();
Returns the Frobenius Norm (Euclidian Norm) of a complex matrix, aa.

public double oneNorm ()
Usage:                      b = aa.oneNorm();
Returns the One Norm of a complex matrix, aa.

public double infinityNorm ()
Usage:                      b = aa.infinityNorm();
Returns the Infinity Norm of a complex matrix, aa.

### OTHER CLASSES USED BY THIS CLASS

This class uses the following classes in this library: