Michael Thomas Flanagan's Java Scientific Library

Matrix Class:     Real Matrices

      

Last update: 10 September 2020                                                                                                                              PERMISSION TO COPY
Main Page of Michael Thomas Flanagan's Java Scientific Library

This class defines an object that represents a real matrix. The instance variables are: It includes the methods needed for matrix manipulations, for the solution of a set of linear equations, for returning the eigenvalues and eigenvector and some elementary statistical methods.
Complex matrices are handled by separate classes; ComplexMatrix and PhasorMatrix.
Matrix rank analysis is handled by a separate class; RankAnalysis.

import directive: import flanagan.math.Matrix; Related classes

SUMMARY OF CONSTRUCTORS AND METHODS
Constructors public Matrix(int nrow, int ncol)  
public Matrix(int nrow, int ncol, double const)  
public Matrix(double[][] twoD)  
public Matrix(float[][] twoD)  
public Matrix(long[][] twoD)  
public Matrix(int[][] twoD)  
public Matrix(BigDecimal[][] twoD)  
public Matrix(BigInteger[][] twoD)   
public Matrix(ArrayList<Object>[] twoD)  
public Matrix(Vector<Object>[] twoD)  
public Matrix(ArrayMaths[] twoD)  
public Matrix(Matrix matrix)  
Create Special Matrices public void setIdentityMatrix() public static Matrix identityMatrix(int nrow)
public void setUnitMatrix() public static Matrix unitMatrix(int nrow, int ncol)
  public static Matrix unitMatrix(int nrow, int ncol, int ncol)
public void setScalarMatrix(double diagconst)
 public static Matrix scalarMatrix(int nrow, double diagconst)
  public static Matrix scalarMatrix(int nrow, int ncol, double diagconst)
public void setDiagonalMatrix(double[] diag)
 public static Matrix diagonalMatrix(int nrow, double[] diag)
  public static Matrix diagonalMatrix(int nrow, int ncol, double[] diag)
Row Matrix   public static Matrix rowMatrix(double[] oneDarray)
Column Matrix   public static Matrix columnMatrix(double[] oneDarray)
Set values public void setTwoDarray(double[][] twoD)  
public void setElement(int i, int j, double aa)  
public void setSubMatrix(int i, int j, double[][] submat)  
public void setSubMatrix(int i, int j, int k, int l, double[][] submat)  
public void setSubMatrix(int[] row, int[] col, double[][] submat)  
Get values public int getNrow()  
public int getNcol()  
public double[][] getArrayReference()  
public double[][] getArrayCopy()  
public double[] getRowCopy(int i)  
public double[] getColumnCopy(int i)  
public double getElement(int i, int j)  
public Matrix getSubMatrix(int i, int j, int k, int l)  
public Matrix getSubMatrix(int[] row, int[] col)  
public int[] getIndexReference()  
public int[] getIndexCopy()  
public double getSwap()  
Deep Copy public Matrix copy() public static Matrix copy(Matrix aa)
public Object clone()  
Addition public Matrix plus(Matrix bb) public static Matrix plus(Matrix aa, Matrix bb)
public Matrix plus(double[][] bb)  
public void plusEquals(Matrix bb)  
Subtraction public Matrix minus(Matrix bb) public static Matrix minus(Matrix aa, Matrix bb)
public Matrix minus(double[][] bb)  
public void minusEquals(Matrix bb)  
Multiplication public Matrix timesRightSideMatrix(Matrix bb) public static Matrix timesMatrix(Matrix aa, Matrix bb)
public Matrix timesRightSideMatrix(double[][] bb) public static Matrix timesMatrix(Matrix aa, double[][] bb)
public Matrix timesLeftSideMatrix(Matrix bb)  
public Matrix timesLeftSideMatrix(double[][] bb) public static Matrix timesMatrix(double[][] bb, Matrix aa)
public double[] timesRightSideColumnVector(double[] vec) public static double[] timesRightSideColumnVector(Matrix aa, double[] vec)
public Matrix timesLeftSideColumnVector(double[] vec) public static Matrix timesLeftSideColumnVector(double[] bb, Matrix aa)
public Matrix timesRightSideRowVector(double[] vec) public static Matrix timesRightSideRowVector(Matrix aa, double[] vec)
public double[] timesLeftSideRowVector(double[] vec) public static double[] timesLeftSideRowVector(double[] bb, Matrix aa)
public Matrix timesConstant(double bb) public static Matrix timesConstant(Matrix aa, double bb)
public void timesRightSideMatrixEquals(Matrix bb)  
public void timesRightSideMatrixEquals(double[][] bb)
  
public void timesLeftSideMatrixEquals(Matrix bb)  
public void timesLeftSideMatrixEquals(double[][] bb)
  
public void timesConstantEquals(double bb)  
Division public Matrix over(Matrix bb) public static Matrix over(Matrix aa, Matrix bb)
public Matrix over(double[][] bb) public static Matrix over(Matrix aa, double[][] bb)
  public static Matrix over(double[][] aa, double[][] bb)
public void overEquals(Matrix bb)  
public void overEquals(double[][] bb)  
Inverse public Matrix inverse() public static Matrix inverse(Matrix aa)
Transpose public Matrix transpose()  public static Matrix transpose(Matrix aa)
Opposite public Matrix opposite() public static Matrix opposite(Matrix aa)
Reduced Row Echelon Form public Matrix reducedRowEchelonForm()
  
Hessenberg matrix public double[][] getHessenbergMatrix()
  
Trace public double trace() public static double trace(Matrix aa)
Determinant public double determinant() public static double determinant(Matrix aa)
  public static double determinant(double[][] aa)
public double logDeterminant() public static double logDeterminant(Matrix aa)
  public static double logDeterminant(double[][] aa)
Cofactor public Matrix cofactor()  
public double cofactor(int i, int j)  
Norms public double frobeniusNorm()  
public double oneNorm()  
public double infinityNorm()  
Eigenvalues and eigenvectors public double[] getEigenValues()
  
public double[] getSortedEigenValues()
  
public double[][] getEigenVectorsAsRows()
   #
public double[][] getEigenVectorsAsColumns()
  
public double[][] getSortedEigenVectorsAsRows()
  
public double[][] getSortedEigenVectorsAsColumns()
  
public int[][] eigenValueIndices()
  
public int getNumberOfJacobiRotations()
  
LU Decompostion public Matrix luDecomp()  
public double luBackSub(double[] bvec)  
public void resetLUzero(double luZero)  
Linear Equation Set public double[] solveLinearSet(double[] bvec)  
Pivot public int[] pivot()  
Maximum element public double[] maximumElement()  
public double[] rowMaxima()  
public double[] columnMaxima()  
Minimum element public double[] minimumElement()  
public double[] rowMinima()  
public double[] columnMinima()  
Range public double range()  
public double[] rowRanges()  
public double[] columnRanges()  
Sum of elements public double sum()  
public double[] rowSums()  
public double[] columnSums()  
Mean of elements public double mean()  
public double[] rowMeans()  
public double[] columnMeans()  
Subtract the mean of elements public Matrix subtractMean()  
public Matrix subtractRowMeans()  
public Matrix subtractColumnMeans()  
Median of elements public double median()  
public double[] rowMedians()  
public double[] columnMedians()  
Set variance denominator et al. public void setDenominatorToN()  
Variance of elements public double variance()  
public double[] rowVariances()  
public double[] columnVariances()  
Standard deviation of elements public double standardDeviation()  
public double[] rowStandardDeviations()  
public double[] columnStandardDeviations()  
Standard error of elements public double standardError()  
public double[] rowStandardErrors()  
public double[] columnStandardErrors()  
Logical tests public boolean isSquare()
  
public boolean isSymmetric()
public boolean isNearlySymmetric(double tolerance)
public boolean isIdentity()
public boolean isNearlyIdentity(double tolerance)
public boolean isUnit()
public boolean isNearlyUnit(double tolerance)
public boolean isZero()
public boolean isNearlyZero(double tolerance)
public boolean isDiagonal()
public boolean isNearlyDiagonal(double tolerance)
public boolean isLowerTriagonal()
public boolean isNearlyLowerTriagonal(double tolerance)
public boolean isUpperTriagonal()
public boolean isNearlyUpperTriagonal(double tolerance)
public boolean isTridiagonal()
public boolean isNearlyTridiagonal(double tolerance)
public boolean isLowerHessenberg()
public boolean isNearlyLowerHessenberg(double tolerance)
public boolean isUpperHessenberg()
public boolean isNearlyUpperHessenberg(double tolerance)
public boolean isSingular()
public boolean isNearlySingular(double tolerance)
public ArrayList<Integer> identicalRows()
public ArrayList<Integer> identicalColumns()
public ArrayList<Integer> zeroRows()
public ArrayList<Integer> zeroColumns()


CONSTRUCTORS

 public Matrix(int nrow, int ncol)
Usage:                      Matrix aa = new Matrix(nrow, ncol);
This creates a new instance of Matrix, aa, with a a nrow x ncol matrix of double variables and initialises all to zero.

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

public Matrix(double[][] twoD)
public Matrix(float[][] twoD)
public Matrix(long[][] twoD)
public Matrix(int[][] twoD)
public Matrix(BigDecimal[][] twoD)
public Matrix(BigInteger[][] twoD)
public Matrix(ArrayList<Object>[] twoD)
public Matrix(Vector<Object>[] twoD)
public Matrix(ArrayMaths[] twoD)
public Matrix(Matrix twoD)
Usage:                      Matrix aa = new Matrix(twoD);
This creates a new instance of Matrix, aa, with an internal two dimensional array of elements, stored as doubles, copied from the object passed as twoD in the above usage.
The object twoD may be
See also setTwoDarray() and copy()


CREATE SPECIAL MATRICES
Identity Matrix
Instance method
public void setIdentityMatrix()
Usage:                      aa.setIdentityMatrix();
Converts the stored matrix of the instance of Matrix aa to an n x n identity matrix [all diagonal elements = 1, all off-diagonal elements = 0] in which n equals the number of rows and columns in the stored matrix. An exception is thrown if the number of rows does not equal the number of columns.

Static method
public static Matrix identityMatrix(int nrow)
Usage:                      aa = Matrix.identityMatrix(n);
Creates an n x n identity matrix [all diagonal elements = 1, all off-diagonal elements = 0].

Unit Matrix
Instance methods
public void setUnitMatrix()
Usage:                      aa .setUnitMatrix();
Converts the stored matrix of the instance of Matrix aa to an n x m unit matrix [all elements = 1] in which n equals the number of rows and m equals the number of columns in the stored matrix.

Static method
public static Matrix unitMatrix(int nrow)
Usage:                      aa = Matrix.unitMatrix(n);
Converts the stored matrix of the instance of Matrix aa to an n x m unit matrix [all elements = 1] in which n equals the number of rows and m equals the number of columns in the stored matrix.

public static Matrix unitMatrix(int nrow, int ncol)
Usage:                      aa = Matrix.unitMatrix(n, m);
Creates a rectangular n x m unit matrix [all elements = 1].

Scalar Matrix
Instance methods
public void setScalarMatrix(double diagconst)
Usage:                      aa.scalarMatrix(diagconst);
Converts the stored matrix of the instance of Matrix aa to an n x m scalar matrix [all diagonal elements = the same number (diagconst), all off-diagonal elements = 0] in which n equals the number of rows and m equals the number of columns in the stored matrix.

Static method
public static Matrix scalarMatrix(int nrow, double diagconst)
Usage:                      aa = Matrix.scalarMatrix(n, diagconst);
Creates a square n x n scalar matrix [all diagonal elements = the same number (diagconst), all off-diagonal elements = 0].

public static Matrix scalarMatrix(int nrow, int ncol, double diagconst)
Usage:                      aa = Matrix.scalarMatrix(n, m, diagconst);
Creates a rectangular n x m scalar matrix [all diagonal elements = the same number (diagconst), all off-diagonal elements = 0].

Diagonal Matrix
Instance methods
public void setDiagonalMatrix(double[] diag)
Usage:                      aa.setDiagonalMatrix(diag);
Converts the stored matrix of the instance of Matrix aa to an n x m diagonal matrix with the diagonal elements equal to the double array, diag, entered as an array of doubles, and with all off-diagonal elements = 0. in which n equals the number of rows and m equals the number of columns in the stored matrix.

Static methods
public static Matrix diagonalMatrix(int nrow, double[] diag)
Usage:                      aa = Matrix.diagonalMatrix(n, diag);
Creates a square n x n diagonal Matrix.with the diagonal elements = the double array, diag, and all off-diagonal elements = 0.

public static Matrix diagonalMatrix(int nrow, int ncol, double[] diag)
Usage:                      aa = Matrix.diagonalMatrix(n, m, diag);
Creates a rectangular n x m diagonal matrix with the diagonal elements = the double array, diag, and all off-diagonal elements = 0.


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


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


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

public setElement(int i, int j, double aa)
Usage:                      aa.setElement(i, j, x);
Sets the members of the internal 2D array element, of matrix of aa, matrix[i][j] to x.

public setSubMatrix(int i, int j, double[][] 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 double array submat.

public setSubMatrix(int i, int j, int k, int l, double[][] 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 double array submat. Method above does the same more conveniently. This method retained for backward compatibity.

public setSubMatrix(int[] row, int[] col, double[][] 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 double 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 double[][] getArrayReference()
Usage:                      xx = aa.getArrayReference();
Returns a reference (pointer) to the internal 2D array, matrix.

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

public double[] getRowCopy(int i)
Usage:                      row = aa.getRowCopy(i);
Returns a copy of the ith row (indices start at 0).

public double[] getColumnCopy(int i)
Usage:                      row = aa.getColumnCopy(i);
Returns a copy of the ith column (indices start at 0).

public double getElementReference(int i, int j)
Usage:                      xx = aa.getElement(i,j);
Returns the internal 2D array element, matrix[i][j].

public Matrix getSubMatrix(int i, int j, int k, int l)
public Matrix 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 Matrix
public Matrix copy()
public Object clone()
public static Matrix copy(Matrix aa)
Usage:                      bb = aa.copy();
Usage:                      bb = Matrix.copy(aa);
A deep copy of the Matrix instance, aa, is returned.

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


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

Usage:                      cc = Matrix.plus(aa, bb);
Performs the operation cc = aa + bb where aa, bb and cc are Matrix.

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


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

Usage:                      cc = Matrix.minus(aa, bb);
Performs the operation cc = aa - bb where aa, bb and cc are Matrix.

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


MULTIPLICATION
instance methods
public Matrix timesRightSideMatrix(Matrix bb)
public Matrix timesRightSideMatrix(double[][] bb)
Usage:                      cc = aa.timesRightSideMatrix(bb);
Performs the operation C = A*B where A is the stored matrix in the instance of the Matrix, aa and B is the matrix supplied through the argument bb, as either an instance of Matrix or a 2D array of doubles, and is on the right hand side of matrix A in the matrix multiplication operation. The returned value, C (cc), is a Matrix. The original stored matrix A is unaltered.

public Matrix timesLeftSideMatrix(Matrix bb)
public Matrix timesLeftSideMatrix(double[][] bb)
Usage:                      cc = aa.timesLeftSideMatrix(bb);
Performs the operation C = B*A where A is the stored matrix in the instance of the Matrix, aa and B is the matrix supplied through the argument bb, as either an instance of Matrix or a 2D array of doubles, and is on the left hand side of matrix A in the matrix multiplication operation. The returned value, C (cc), is a Matrix. The original stored matrix A is unaltered.

public double[] timesRightSideColumnVector(double[] vec)
Usage:                      cc = aa.timesRightSideColumnVector(bb);
Performs the operation C = A*B where A is the stored matrix in the instance of the Matrix, aa and B is a column vector supplied through the argument bb, as a 2D array of doubles, and is on the right hand side of matrix A in the matrix-vector multiplication operation. The returned value, C (cc), is an array of doubles (a vector). The original stored matrix A is unaltered.

public Matrix timesLeftSideColumnVector(double[] vec)
Usage:                      cc = aa.timesLeftSideColumnVector(bb);
Performs the operation C = B*A where A is the stored matrix in the instance of the Matrix, aa and B is a column vector supplied through the argument bb, as a 2D array of doubles, and is on the left hand side of matrix A in the matrix-vector multiplication operation. The returned value, C (cc), is a Matrix. The original stored matrix A is unaltered.

public Matrix timesRightSideRowVector(double[] vec)
Usage:                      cc = aa.timesRightSideRowVector(bb);
Performs the operation C = A*B where A is the stored matrix in the instance of the Matrix, aa and B is a row vector supplied through the argument bb, as a 2D array of doubles, and is on the right hand side of matrix A in the matrix-vector multiplication operation. The returned value, C (cc), is a Matrix. The original stored matrix A is unaltered.

public double[] timesLeftSideRowVector(double[] vec)
Usage:                      cc = aa.timesLeftSideColumnVector(bb);
Performs the operation C = B*A where A is the stored matrix in the instance of the Matrix, aa and B is a row vector supplied through the argument bb, as a 2D array of doubles, and is on the left hand side of matrix A in the matrix-vector multiplication operation. The returned value, C (cc), is an array of doubles (a vector). The original stored matrix A is unaltered.

public Matrix timesConstant(double bb)
Usage:                      cc = aa.timesConstant(bb);
Performs the operation C = A*B where A is the stored matrix in the instance of the Matrix, aa and B is a constant supplied through the argument bb, as a double. The returned value, C (cc), is a Matrix. The original stored matrix A is unaltered.

Static methods
public static Matrix timesMatrix(Matrix aa, Matrix bb)
public static Matrix timesMatrix(Matrix aa, double[][] bb)
public static Matrix timesMatrix(double[][] bb, Matrix aa)
Usage:                      cc = Matrix.timesMatrix(aa, bb);
Performs the operation C = A*B where A and B are the matrices entered as the arguments aa and bbas either an instance of Matrix or a 2D array of double. The order of A and B in the matrix multiplication operation is the same as their order in the list of entered arguments. The returned value, C (cc), is a Matrix. The original matrices A and B are unaltered.

public static double[] timesRightSideColumnVector(Matrix aa, double[] bb)
Usage:                      cc = Matrix.timesRightSideColumnVector(aa, bb);
Performs the operation C = A*B where A is matrix entered as the argument aa and B is a column vector entered as the argument bb, as an array of doubles, and is on the right hand side of A in the matrix-vector multiplication procedure. The returned value, C (cc), is an array of doubles (a vector). A and B are unaltered.

public static Matrix timesLeftSideColumnVector(double[] bb, Matrix aa)
Usage:                      cc = Matrix.timesLeftSideColumnVector(bb, aa);
Performs the operation C = B*A where A is matrix entered as the argument aa and B is a column vector entered as the argument bb, as an array of doubles, and is on the rleft hand side of A in the matrix-vector multiplication procedure. The returned value, C (cc), is a Matrix. A and B are unaltered.

public static Matrix timesRightSideRowVector(Matrix aa, double[] bb)
Usage:                      cc = Matrix.timesRightSideRowVector(aa, bb);
Performs the operation C = A*B where A is matrix entered as the argument aa and B is a row vector entered as the argument bb, as an array of doubles, and is on the right hand side of A in the matrix-vector multiplication procedure. The returned value, C (cc), is a Matrix. A and B are unaltered.

public static double[] timesLeftSideRowVector(double[] bb, Matrix aa)
Usage:                      cc = Matrix.timesLeftSideRowVector(bb, aa);
Performs the operation C = B*A where A is matrix entered as the argument aa and B is a column vector entered as the argument bb, as an array of doubles, and is on the rleft hand side of A in the matrix-vector multiplication procedure. The returned value, C (cc), is an array od=f doubles (a vector). A and B are unaltered.

public static Matrix timesConstant(Matrix aa, double bb)
Usage:                      cc = Matrix.times(aa, bb);
Performs the operation C = A*B where A is a matrix entered as the argument, aa and B is a constant supplied through the argument bb, as a double. The returned value, C (cc) is a Matrix. A abd B are unaltered.

Equivalence of the *= operator
public void timesRightSideMatrixEquals(Matrix bb)
public void timesRightSideMatrixEquals(double[][] bb)
Usage:                      aa.timesRightSideMatrixEquals(bb);
Performs the operation A = A*B where A is the matrix stored in the instance of Matrix aa and B is the matrix supplied as argument bb as either a Matrix or a 2D array of doubles. Matrix B lies on the right hand side of A in the matrix multiplication operation. The product of the multiplication operation replaces the stored matrix in the instance a Matrix aa.

public void timesLeftSideMatrixEquals(Matrix bb)
public void timesLeftSideMatrixEquals(double[][] bb)
Usage:                      aa.timesLeftSideMatrixEquals(bb);
Performs the operation A = B*A where A is the matrix stored in the instance of Matrix aa and B is the matrix supplied as argument bb as either a Matrix or a 2D array of doubles. Matrix B lies on the left hand side of A in the matrix multiplication operation. The product of the multiplication operation replaces the stored matrix in the instance a Matrix aa.

public void timesConstantEquals(double bb)
Usage:                      aa.timesConstantEquals(bb);
Performs the operation A = A*B where A is the matrix stored in the instance of Matrix aa and B is constant supplied as the argument bb as a double. The product of the multiplication operation replaces the stored matrix in the instance a Matrix aa.

DIVISION
public Matrix over(Matrix bb)
public Matrix over(double[][] bb)
Usage:                      cc = aa.over(bb);
Performs the operation C = AB-1 where A, B and C are matrices and B-1 is the inverse of B. A is the matrix stored in the instance of Matrix, aa, B is supplied as the argument bb, either as a Matrix or a 2D array of doubles, and C is returned as cc

public static Matrix over(Matrix aa, Matrix bb)
public static Matrix over(Matrix aa, double[][] bb)
public static Matrix over(double[][] aa, double[][] bb)
Usage:                      cc = Matrix.over(aa, bb);
Performs the operation C = AB-1 where A, B and C are matrices and B-1 is the inverse of B. A and B are supplied as the arguments aa and bb, either as a Matrix or a 2D array of doubles, and C is returned as cc.

Equivalence of the *= operator
public void overEquals(Matrix bb)
public void overEquals(double[][] bb)
Usage:                      aa.overEquals(bb);
Performs the operation A = AB-1 where A, B are matrices and B-1 is the inverse of B. A is the matrix stored in the instance of Matrix, aa, B is supplied as the argument bb, either as a Matrix or a 2D array of doubles. The result of the division replaces the matrix A in the instance of Matrix , aa.

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


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


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


LU DECOMPOSITION
public Matrix luDecomp()
Usage:                      lu = aa.luDecomp();
Returns the LU decomposition of a 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 follows their approach but adapted to an object-oriented language.

public double luBackSub(double[] bvec)
Usage:                      xx = lu.luDecomp(bb);
The forward and backward substitution procedure associated with the LU decompostion when used to solves the linear set of equations A.x = b. luBackSub actually solves L.x = b where L is the 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.

public void resetLUzero(double luZero)
Usage:                      lu.resetLUzero(luZero);
The LU decompostion replaces some calculation intermediate array values that are zero by a small number to maintain numerical stability. The default value of this small number is 1 x 10-100. This method allows the user to reset this value as the argument luZero or to remove it entirely, i.e. set luZero to 0.0.


SOLUTION OF A SET OF LINEAR EQUATIONS
public double solveLinearSet(double[] b)
Usage:                      x = a.solveLinearSet(b);
Solves the linear set of equations A.x = b where A is the matrix of coefficients, b is the right-hand side vector and x is the vector of solution values.
Square matrix
In the case of a square matrix, i.e. the number of unknowns equals the number of equations, this method uses an LU decomposition [luDecomp() and luBackSub() - see above]. No information on the well-conditioned/ill-conditioned state of the linear equations is provided hence care is needed in using this method.

Overdetermined linear equations
If the number of equations is greater than the number of unknowns, i.e. the number of rows of matrix A is greater than the number of columns and the length of vector b is equal to the number of rows of matrix A, a minimisation of the least squares |A.x − b|2 is used to obtain the best estimates of x. This procedure is not recommended unless the user is aware of the problems associated with solving overdetermined equations.


EIGEN VALUES AND EIGENVECTORS OF SYMMETRIC MATRICES
For a discussion of eigen systems and of the Jacobi procedure used in this class 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/.
public double[] getEigenValues()
public double[] getSortedEigenValues()
public double[][] getEigenVectorsAsRows()
public double[][] getEigenVectorsAsColumns()
public double[][] getSortedEigenVectorAsRows()
public double[][] getSortedEigenVectorAsColumns()
public int[][] eigenValueIndices()
public int getNumberOfJacobiRotations()
Usage:                      eigenvalues = aa.getEigenValues();
This method returns the eigenvalues of a symmetric matrix stored in the instance, aa, as calculated.

Usage:                      eigenvalues = aa.getSortedEigenValues();
This method returns the eigenvalues of a symmetric matrix stored in the instance, aa, sorted into a descending order.

Usage:                      eigenvector = aa.getEigenVectorsAsRows();
This method returns the eigenvectors of a symmetric matrix stored in the instance, aa, as calculated and returned as the vector corresponding to each eigenvalue stored as a row.

Usage:                      eigenvector = aa.getEigenVectorsAsColumns();
This method returns the eigenvectors of a symmetric matrix stored in the instance, aa, as calculated and returned as the vector corresponding to each eigenvalue stored as a column. This method replaces getEigenVector() which has been retained in the flanagan.jar file.

Usage:                      eigenvector = aa.getSortedEigenVectorAsRows();
This method returns the eigenvectors of a symmetric matrix stored in the instance, aa, reordered to match a descending order of eigen values and returned as the vector corresponding to each eigenvalue stored as a row.

Usage:                      eigenvector = aa.getSortedEigenVectorAsColumns();
This method returns the eigenvectors of a symmetric matrix stored in the instance, aa, reordered to match a descending order of eigen values and returned as the vector corresponding to each eigenvalue stored as a column. This method replaces getSortedEigenVector() which has been retained in the flanagan.jar file.

Usage:                      indices = aa.eigenValueIndices()();
This method returns the indices of the eigenvalues as calculated, i.e. before sorting into a descending order.

Usage:                      nrot = aa.getNumberOfJacobiRotations();
This method returns the number of rotations used in the Jacobi procedure.


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


HESSENBERG MATRIX
public double[][] getHessenbergMatrix()
Usage:                      hessenberg = aa.getHessenbergMatrix();
This method calculates and returns the equivalent Hessenberg matrix.


TRACE
public double trace()
public static double trace(Matrix aa)
Usage:                      b = aa.trace();
Usage:                      b = Matrix.trace(aa);
Returns the trace of a matrix, aa.


DETERMINANT
public double determinant()
public static double determinant(Matrix aa)
public static double determinant(double[][] aa)
Usage:                      b = aa.determinant();
Usage:                      b = Matrix.determinant(aa);
Returns the determinant of a square matrix, aa.

public double logDeterminant()
public static double logDeterminant(Matrix aa)
public static double logDeterminant(double[][] aa)
Usage:                      b = aa.logDeterminant();
Usage:                      b = Matrix.logDeterminant(aa);
Returns the natural logarithm of the determinant of a square matrix, aa. Useful if determinant() underflows or overflows.


COFACTOR
public double cofactor(int i, int j)
public Matrix 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 of a matrix, aa.
This norm is sometimes referred to as the Euclidian Norm but this may lead to confusion with other uses of the term Euclidean norm.
public double oneNorm()
Usage:                      b = aa.oneNorm();
Returns the One Norm of a matrix, aa.

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


PIVOT
public int[] pivot()
Usage:                      aa.pivot();
Usage:                      indices = aa.pivot();
This method swaps the relevant rows and columns in the internal array of aa to place the element of largest absolute value in the top left hand corner of the array, i.e. at postion, element[0][0]. The method also returns, as an array of two int, the index of the row and the index of the column that were exchanged with the zeroth row and the zeroth column


MAXIMUM ELEMENTS
public double[] maximumElement()
public double[] rowMaxima()
public double[] columnMaxima()
Usage:                      maxdetails = aa.maximumElement();
Returns an array of three doubles that contain
Usage:                      maxima = aa.rowMaxima();
This method returns the maxima of the rows.

Usage:                      maxima = aa.columnMaxima();
This method returns the maxima of the columns.


MINIMUM ELEMENTS
public double[] minimumElement()
public double[] rowMinima()
public double[] columnMinima()
Usage:                      mindetails = aa.minimumElement();
Returns an array of three doubles that contain
Usage:                      minima = aa.rowMinima();
This method returns the minima of the rows.

Usage:                      minima = aa.columnMinima();
This method returns the minima of the columns.


RANGES
public double range()
public double[] rowRanges()
public double[] columnRanges()
Usage:                      range = aa.range();
This method returns the range of the elements, i.e. the maximum element value minus the minimum element value.

Usage:                      ranges = aa.rowRanges();
This method returns the ranges of the rows, i.e. the maximum element value minus the minimum element for each row.

Usage:                      ranges = aa.columnRanges();
This method returns the ranges of the columns, i.e. the maximum element value minus the minimum element for each column.


SUMS
public double sum()
public double[] rowSums()
public double[] columnSums()
Usage:                      sum = aa.sum();
This method returns the sum of all the elements.

Usage:                      sums = aa.rowSums();
This method returns the sums of the rows.

Usage:                      sums = aa.columnSums();
This method returns the sums of the columns.


MEANS
public double mean()
public double[] rowMeans()
public double[] columnMeans()
Usage:                      mean = aa.mean();
This method returns the mean of all the elements.

Usage:                      means = aa.rowMeans();
This method returns the means of the rows.

Usage:                      means = aa.columnMeans();
This method returns the means of the columns.


SUBTRACT THE MEANS
public Matrix subtractMean()
public Matrix subtractRowMeans()
public Matrix subtractColumnMeans()
Usage:                      mat = aa.subtractMean();
This method returns a matrix, mat, whose elements are the original elements of the instance, aa, minus the mean of all elements.

Usage:                      mat = aa.subtractRowMeans();
This method returns a matrix mat, whose rows are the elements of the original rows of the instance, aa, minus the mean of the elements of the relevant row.

Usage:                      mat = aa.subtractColumnMeans();
This method returns a matrix mat, whose columns are the elements of the original columns of the instance, aa, minus the mean of the elements of the relevant column.


MEDIANS
public double median()
public double[] rowMedians()
public double[] columnMedians()
Usage:                      median = aa.median();
This method returns the median of all the elements.

Usage:                      medians = aa.rowMedians();
This method returns the medians of the rows.

Usage:                      medians = aa.columnMedians();
This method returns the medians of the columns.


SET VARIANCE DENOMINATOR TO N

public void setDenominatorToN()
Usage:                      aa.setDenominatorToN();
This method sets the denominator in calculations of variance and standard deviation to the number of data points, n. The default value is n−1. See Stat class for details.



VARIANCES
public double variance()
public double[] rowVariances()
public double[] columnVariances()
Usage:                      variance = aa.variance();
This method returns the variance of all the elements.

Usage:                      variances = aa.rowVariances();
This method returns the variances of the rows.

Usage:                      variances = aa.columnVariances();
This method returns the variances of the columns.
See Stat class and Set the denominator for definitions


STANDARD DEVIATIONS
public double standardDeviation()
public double[] rowStandardDeviations()
public double[] columnStandardDeviations()
Usage:                      standardDeviation = aa.standardDeviation();
This method returns the standard deviation of all the elements.

Usage:                      standardDeviations = aa.rowStandardDeviations();
This method returns the standard deviations of the rows.

Usage:                      standardDeviations = aa.columnStandardDeviations();
This method returns the standard deviations of the columns.
See Stat class and Set the denominator for definitions


STANDARD ERRORS
public double standardError()
public double[] rowStandardErrors()
public double[] columnStandardErrors()
Usage:                      standardError = aa.standardError();
This method returns the standard error of all the elements.

Usage:                      standardErrors = aa.rowStandardErrors();
This method returns the standard errors of the rows.

Usage:                      standardErrors = aa.columnStandardErrors();
This method returns the standard errors of the columns.
See Stat class and Set the denominator for definitions


LOGICAL TESTS
Square matrix
public boolean isSquare()
Usage:                      test = aa.isSquare();
Returns true if matrix, aa, is a square matrix; returns false if it is not.

Symmetric matrix
public boolean isSymmetric()
Usage:                      test = aa.isSymmetric();
Returns true if matrix, aa, is a symmetric; returns false if it is not.

public boolean isNearlySymmetric(double tolerance)
Usage:                      test = aa.isNearlySymmetric(tolerance);
Returns true if matrix, aa, is nearly symmetric, i.e. if the absolute value of the difference between the pairs of elements that should be zero is less than the user supplied tolerance, tolerance; returns false if they are not.

Identity matrix
public boolean isIdentity()
Usage:                      test = aa.isIdentity();
Returns true if matrix, aa, is an identity matrix; returns false if it is not.

public boolean isNearlyIdentity(double tolerance)
Usage:                      test = aa.isNearlyIdentity(tolerance);
Returns true if matrix, aa, is nearly an identity matrix, i.e. if the absolute values of the off-diagonal elements are all less than the user supplied tolerance, tolerance and the absolute value of each (diagonal element - unity) is also less than the user supplied tolerance, tolerance; returns false if they are not.

Unit matrix
public boolean isUnit()
Usage:                      test = aa.isUnit();
Returns true if matrix, aa, is a unit matrix, i.e., all elements equal unity; returns false if it is not.

public boolean isNearlyUnit(double tolerance)
Usage:                      test = aa.isNearlyUnit(tolerance);
Returns true if matrix, aa, is nearly a unit matrix, i.e. if the absolute value of each (element - unity) is also less than the user supplied tolerance, tolerance; returns false if they are not.

Zero matrix
public boolean isZero()
Usage:                      test = aa.isUnit();
Returns true if matrix, aa, is a zero matrix; returns false if it is not.

public boolean isNearlyZero(double tolerance)
Usage:                      test = aa.isNearlyZero(tolerance);
Returns true if matrix, aa, is nearly a zero matrix, i.e. if the absolute values of all the elements are less than the user supplied tolerance, tolerance; returns false if they are not.

Diagonal matrix
public boolean isDiagonal()
Usage:                      test = aa.isDiagonal();
Returns true if matrix, aa, is a diagonal matrix; returns false if it is not.

public boolean isNearlyDiagonal(double tolerance)
Usage:                      test = aa.isNearlyDiagonal(tolerance);
Returns true if matrix, aa, is nearly a diagonal matrix, i.e. if the absolute values of all the off-diagonal elements are less than the user supplied tolerance, tolerance; returns false if they are not.

Upper Triagonal matrix
public boolean isUpperTriagonal()
Usage:                      test = aa.isUpperTriagonal();
Returns true if matrix, aa, is an upper triagonal matrix; returns false if it is not.

public boolean isNearlyUpperTriagonal(double tolerance)
Usage:                      test = aa.isNearlyUpperTriagonal(tolerance);
Returns true if matrix, aa, is nearly an upper triagonal matrix, i.e. if the absolute values of all the off-diagonal elements in the lower traingle below the diagonal are less than the user supplied tolerance, tolerance; returns false if they are not. A nearly diagonal matrix returns false.

Lower Triagonal matrix
public boolean isLowerTriagonal()
Usage:                      test = aa.isLowerTriagonal();
Returns true if matrix, aa, is a lower triagonal matrix; returns false if it is not.

public boolean isNearlyLowerTriagonal(double tolerance)
Usage:                      test = aa.isNearlyLowerTriagonal(tolerance);
Returns true if matrix, aa, is nearly a lower triagonal matrix, i.e. if the absolute values of all the off-diagonal elements in the upper traingle above the diagonal are less than the user supplied tolerance, tolerance; returns false if they are not. A nearly diagonal matrix returns false.

Tridiagonal matrix
public boolean isTridiagonal()
Usage:                      test = aa.isTridiagonal();
Returns true if matrix, aa, is a tridiagonal matrix; returns false if it is not.

public boolean isNearlyTridiagonal(double tolerance)
Usage:                      test = aa.isNearlyTridiagonal(tolerance);
Returns true if matrix, aa, is a nearly a tridiagonal matrix, i.e. if the absolute values of the off-diagonal elements above the first superdiagonal and below the first subdiagonal are all less than the user supplied tolerance, tolerance; returns false if they are not.

Upper Hessenberg matrix
public boolean isUpperHessenberg()
Usage:                      test = aa.isUpperHessenberg();
Returns true if matrix, aa, is an upper Hessenberg matrix; returns false if it is not.

public boolean isNearlyUpperHessenberg(double tolerance)
Usage:                      test = aa.isNearlyUpperHessenberg(tolerance);
Returns true if matrix, aa, is nearly an upper Hessenberg matrix, i.e. if the absolute values of the diagonal elements below the first subdiagonal are all less than the user supplied tolerance, tolerance; returns false if they are not.

Lower Hessenberg matrix
public boolean isLowerHessenberg()
Usage:                      test = aa.isLowerHessenberg();
Returns true if matrix, aa, is a lower Hessenberg matrix; returns false if it is not.

public boolean isNearlyLowerHessenberg(double tolerance)
Usage:                      test = aa.isNearlyLowerHessenberg(tolerance);
Returns true if matrix, aa, is a nearly a lower Hessenberg matrix, i.e. if the absolute values of the off-diagonal elements above the first superdiagonal are less than the user supplied tolerance, tolerance; returns false if they are not.

Singular matrix
public boolean isSingular()
Usage:                      test = aa.isSingular();
Returns true if matrix, aa, is singular; returns false if it is not.

public boolean isNearlySingular(double tolerance)
Usage:                      test = aa.isNearlySingular(tolerance);
Returns true if matrix, aa, is a nearly singular, i.e. if the absolute values of the determinant less than the user supplied tolerance, tolerance; returns false if it is not.

Check for identical rows
public ArrayList<Integer> identicalRows()
Usage:                      list = aa.identicalRows();
This method checks whether any of the rows are identical. If two or more rows are identical it returns, as an ArrayList, the number of identical pairs of rows followed by the row indices of each pair of identical rows. If no rows are identical it returns, as an ArrayList, the integer 0.

Check for identical columns
public ArrayList<Integer> identicalColumns()
Usage:                      list = aa.identicalColumns();
This method checks whether any of the columns are identical. If two or more columns are identical it returns, as an ArrayList, the number of identical pairs of columns followed by the column indices of each pair of identical columns. If no columns are identical it returns, as an ArrayList, the integer 0.

Check for rows containing only zero elements
public ArrayList<Integer> zeroRows()
Usage:                      list = aa.zeroRows();
This method checks whether any of the rows contain only zero elements. If one or more rows contain only zeros it returns, as an ArrayList, the number of such rows followed by their row indices. If there are no such rows it returns, as an ArrayList, the integer 0.

Check for rows containing only zero elements
public ArrayList<Integer> zeroRows()
Usage:                      list = aa.zeroRows();
This method checks whether any of the rows contain only zero elements. If one or more rows contain only zeros it returns, as an ArrayList, the number of such rows followed by their row indices. If there are no such rows it returns, as an ArrayList, the integer 0.

Check for columns containing only zero elements
public ArrayList<Integer> zeroColumns()
Usage:                      list = aa.zeroColumns();
This method checks whether any of the columns contain only zero elements. If one or more columns contain only zeros it returns, as an ArrayList, the number of such columns followed by their column indices. If there are no such rows it returns, as an ArrayList, the integer 0.


OTHER CLASSES USED BY THIS CLASS

 This class uses the following classes in this library:


PERMISSION TO COPY

Permission to use, copy and modify this software and its documentation for NON-COMMERCIAL purposes is granted, without fee, provided that an acknowledgement to the author, Dr Michael Thomas Flanagan at www.ee.ucl.ac.uk/~mflanaga, appears in all copies and associated documentation or publications. Dr Michael Thomas Flanagan makes no representations about the suitability or fitness of the software for any or for a particular purpose. Dr Michael Thomas Flanagan shall not be liable for any damages suffered as a result of using, modifying or distributing this software or its derivatives.

Redistributions of the source code of this class, or parts of the source codes, must retain the copyright notice, this list of conditions and the following disclaimer (all at the top of the source code) and requires written permission from the Michael Thomas Flanagan:

Redistribution in binary form of all or parts of this class must reproduce the copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution and requires written permission from the Michael Thomas Flanagan:
.


This page was prepared by Dr Michael Thomas Flanagan