The mathIT Library
A Java™ API for mathematics
org.mathIT.algebra

Class Matrix

• ```public class Matrix
extends Object```
This class enables to construct a matrix which can be manipulated by various matrix operations.
Version:
2.0
Author:
Andreas de Vries
• Field Summary

Fields
Modifier and Type Field and Description
`protected int` `columns`
Number of columns of this matrix.
`protected double` `dominantEigenvalue`
The dominant eigenvalue of this matrix.
`protected double[]` `dominantEigenvector`
An eigenvector associated to the dominant eigenvalue of this matrix.
`protected EigenvalueDecomposition` `eigenvalueDecomposition`
The eigenvalue decomposition of this matrix.
`static double` `EPSILON`
Constant which defines the corridor around 0.0 where a number of type double is considered as to be zero.
`protected double[][]` `matrix`
Entries of this matrix.
`protected int` `rows`
Number of rows of this matrix.
• Constructor Summary

Constructors
Constructor and Description
`Matrix(double[] vector)`
Constructs a matrix (1 × n) matrix from the given one-dimensional array.
`Matrix(double[][] matrix)`
Constructs a matrix from the given two-dimensional array.
```Matrix(double[][] matrix, int rows, int columns)```
Constructs a matrix from the given two-dimensional array.
`Matrix(int[][] matrix)`
Constructs a matrix from the given two-dimensional array.
```Matrix(int rows, int columns)```
Constructs a zero matrix with the given rows and columns.
• Method Summary

All Methods
Modifier and Type Method and Description
`Matrix` `add(Matrix b)`
Returns the sum of this matrix with the given matrix b.
`Matrix` `adjugate()`
Returns the adjugate of this matrix.
`double` ```cofactor(int i, int j)```
Returns the cofactor Cij = (-1)i + j Mij of this matrix, where Mij denotes the minor.
`double` `cond()`
Returns the two norm condition number defined as the ratio smax/smin of the maximum and the minimum singular value of this matrix.
`Matrix` `copy()`
Returns a copy of this matrix.
`static Matrix` `createIdentity(int n)`
This method creates an (n x n) unity matrix.
`static Matrix` ```createZero(int m, int n)```
Returns the zero (m × n) matrix.
`Matrix[]` `decomposeQR()`
Returns the QR decomposition of this matrix as a pair of matrices.
`double` `det()`
Computes the determinant of this matrix.
`boolean` `equals(double[] a)`
Returns true if and only if all entries of this matrix equal the entries of the specified column vector.
`boolean` `equals(double[][] a)`
Returns true if and only if all entries of this matrix equal the entries of the specified matrix.
`boolean` `equals(Matrix a)`
Returns true if and only if all entries of this matrix equal the entries of the specified matrix.
`double[]` `getColumn(int j)`
Returns the specified column of this matrix.
`int` `getColumns()`
Returns the number of columns of this matrix.
`double` `getDominantEigenvalue()`
Returns the dominant eigenvalue of this matrix with an error `EPSILON`.
`double` `getDominantEigenvalue(double error)`
Returns the dominant eigenvalue of this matrix with the specified error of approximation.
`double[]` `getDominantEigenvector()`
Returns an eigenvector associated to the dominant eigenvalue of this matrix with the error `EPSILON` of approximation.
`double[]` `getDominantEigenvector(double error)`
Returns an eigenvector associated to the dominant eigenvalue of this matrix with the specified error of approximation.
`Matrix` `getEigenvectors()`
Returns a matrix whose columns are the eigenvectors of this matrix.
`double[]` `getImagEigenvalues()`
Returns an array consisting of the imaginary parts of the eigenvalues of this matrix.
`double[][]` `getMatrix()`
Returns this matrix as a two-dimensional array.
`static double` `getNorm(double[] v)`
Returns the norm |v| of the vector v.
`double[]` `getRealEigenvalues()`
Returns an array consisting of the real parts of the eigenvalues of this matrix.
`double[]` `getRow(int i)`
Returns the specified row of this matrix.
`int` `getRows()`
Returns the number of rows of this matrix.
`double` ```getValue(int row, int col)```
Returns the value of the matrix position given by the parameters row and col in the usual mathematical convention, that is, both indices are counted from 1 and terminate at the maximum number of rows or columns, respectively.
`Matrix` `inverse()`
Returns the inverse of this matrix.
`boolean` `isSquare()`
Returns whether this matrix is square.
`boolean` `isSymmetric()`
Returns whether this matrix is symmetric.
`static double[]` ```minus(double[] v, double[] w)```
Returns the subtraction of the vectors v and w.
`Matrix` `minus(Matrix b)`
Returns the difference of this matrix with the given matrix b.
`static double` ```multiply(double[] v, double[] w)```
Returns the scalar product of the vectors v and w.
`static double[]` ```multiply(double a, double[] v)```
Returns the product a*v.
`Matrix` `negative()`
Returns the negative of this matrix.
`double` `norm2()`
Returns the two norm ||A||2 of this matrix.
`Matrix` `plus(Matrix b)`
Returns the sum of this matrix with the given matrix b.
`Matrix` `pow(int n)`
Computes the n-th power of this matrix.
`int` `rank()`
Returns the rank of this matrix.
`void` ```setValue(int row, int col, double value)```
Sets the value into the matrix position given by the parameters row and col in the usual mathematical convention, that is, both indices are counted from 1 and terminate at the maximum number of rows or columns, respectively.
`Matrix` `solve(Matrix b)`
This method solves the n linear equation Ax = b, where A is this matrix and b the given vector.
`static double[][]` `tensor(double[][][] a)`
Returns the tensor product of the matrices a[0], a[1], ..., a[n-1], i.e., a[0] ⊗ a[1] ... a[n-2] ⊗ a[n-1].
`static Matrix` `tensor(Matrix[] a)`
Returns the tensor product of the matrices a[0], a[1], ..., a[n-1], i.e., a[0] ⊗ a[1] ... a[n-2] ⊗ a[n-1].
`double[]` `times(double[] v)`
Returns the (right) product of this matrix with the given column vector v.
`Matrix` `times(Matrix b)`
Returns the (right) product of this matrix with the given matrix b.
`String` `toHTML()`
Returns a String representation of this matrix as an HTML table.
`String` `toHTML(String align)`
Returns a String representation of this matrix as an HTML table where each entry is aligned according to the specified value.
`String` ```toHTML(String align, boolean showZeros)```
Returns a String representation of this matrix as an HTML table where each entry is aligned according to the specified value.
`String` `toString()`
Returns a String representation of this matrix.
`double` `trace()`
Returns the trace of this matrix.
`Matrix` `transpose()`
Returns the transpose of this matrix.
`void` `transposeInPlace()`
Transposes this matrix in place, that is, without using additional space to create a new matrix.
• Methods inherited from class java.lang.Object

`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`
• Field Detail

• EPSILON

`public static final double EPSILON`
Constant which defines the corridor around 0.0 where a number of type double is considered as to be zero. Equality of the number `x` to zero should therefore be checked by
```     if (Math.abs(x) < Matrix.EPSILON) ...
```
instead of `if (x==.0) ...` because of possible rounding errors. For instance, this is important to decide whether a matrix is invertible.
Constant Field Values
• rows

`protected final int rows`
Number of rows of this matrix.
• columns

`protected final int columns`
Number of columns of this matrix.
• matrix

`protected final double[][] matrix`
Entries of this matrix.
• dominantEigenvalue

`protected double dominantEigenvalue`
The dominant eigenvalue of this matrix. It is computed in the method `getDominantEigenvalue()`.
• dominantEigenvector

`protected double[] dominantEigenvector`
An eigenvector associated to the dominant eigenvalue of this matrix. It is computed in the method `getDominantEigenvalue()`.
• eigenvalueDecomposition

`protected EigenvalueDecomposition eigenvalueDecomposition`
The eigenvalue decomposition of this matrix. It is null initially and will be computed if necessary.
• Constructor Detail

• Matrix

```public Matrix(int rows,
int columns)```
Constructs a zero matrix with the given rows and columns.
Parameters:
`rows` - the number of rows of this matrix
`columns` - the number of columns of this matrix
• Matrix

`public Matrix(double[][] matrix)`
Constructs a matrix from the given two-dimensional array.
Parameters:
`matrix` - the matrix entries as an array
• Matrix

`public Matrix(int[][] matrix)`
Constructs a matrix from the given two-dimensional array.
Parameters:
`matrix` - the matrix entries as an array
• Matrix

```public Matrix(double[][] matrix,
int rows,
int columns)```
Constructs a matrix from the given two-dimensional array.
Parameters:
`matrix` - the matrix entries as an array
`rows` - number of rows
`columns` - number of columns
• Matrix

`public Matrix(double[] vector)`
Constructs a matrix (1 × n) matrix from the given one-dimensional array.
Parameters:
`vector` - the matrix entries as an array
• Method Detail

• equals

`public boolean equals(Matrix a)`
Returns true if and only if all entries of this matrix equal the entries of the specified matrix.
Parameters:
`a` - a matrix
Returns:
true if and only if this matrix equals the specified matrix a
• equals

`public boolean equals(double[][] a)`
Returns true if and only if all entries of this matrix equal the entries of the specified matrix.
Parameters:
`a` - a two-dimensional array viewed as a matrix
Returns:
true if and only if this matrix equals the specified matrix a
• equals

`public boolean equals(double[] a)`
Returns true if and only if all entries of this matrix equal the entries of the specified column vector.
Parameters:
`a` - array viewed as a column vector
Returns:
true if and only if this matrix equals the specified matrix a
• getRow

`public double[] getRow(int i)`
Returns the specified row of this matrix.
Parameters:
`i` - row number
Returns:
the i-th row of this matrix
Throws:
`ArrayIndexOutOfBoundsException` - if the index is out of bounds
• getColumn

`public double[] getColumn(int j)`
Returns the specified column of this matrix.
Parameters:
`j` - column number
Returns:
the j-th column of this matrix
Throws:
`ArrayIndexOutOfBoundsException` - if the index is out of bounds
• getRows

`public int getRows()`
Returns the number of rows of this matrix.
Returns:
the number of rows of this matrix
• getColumns

`public int getColumns()`
Returns the number of columns of this matrix.
Returns:
the number of columns of this matrix
• getMatrix

`public double[][] getMatrix()`
Returns this matrix as a two-dimensional array. The array matrix is an attribute of this matrix, but it is returned as a copy.
Returns:
the double array with the entries of this matrix
• getValue

```public double getValue(int row,
int col)```
Returns the value of the matrix position given by the parameters row and col in the usual mathematical convention, that is, both indices are counted from 1 and terminate at the maximum number of rows or columns, respectively.
Parameters:
`row` - the row index (counting from 1) to be set
`col` - the column index (counting from 1) to be set
Returns:
the value Aij with i = row, j = column
• setValue

```public void setValue(int row,
int col,
double value)```
Sets the value into the matrix position given by the parameters row and col in the usual mathematical convention, that is, both indices are counted from 1 and terminate at the maximum number of rows or columns, respectively.
Parameters:
`row` - the row index (counting from 1) to be set
`col` - the column index (counting from 1) to be set
`value` - the value to be set
• isSquare

`public boolean isSquare()`
Returns whether this matrix is square.
Returns:
true if and only if this matrix is square
• isSymmetric

`public boolean isSymmetric()`
Returns whether this matrix is symmetric.
Returns:
true if and only if this matrix is symmetric
• copy

`public Matrix copy()`
Returns a copy of this matrix. Thus this method can be used to clone this matrix.
Returns:
a copy of this matrix
• cond

`public double cond()`
Returns the two norm condition number defined as the ratio smax/smin of the maximum and the minimum singular value of this matrix. This method obtains its result from the `Singular value decomposition` (SVD) of this matrix. This method is convenient to be invoked if only the condition number of the matrix is desired. Since, however, in particular for large matrices it requires substantial computational effort, you may be considering to apply more efficiently the class `SingularValueDecomposition` and its methods.
Returns:
ratio of largest to smallest singular value (smax/smin).
`SingularValueDecomposition.cond()`
• det

`public double det()`
Computes the determinant of this matrix. An exception is thrown if this matrix is not square, since then the determinant is not defined mathematically.
Returns:
the determinant of this matrix
Throws:
`IllegalArgumentException` - if this matrix is not square
• pow

`public Matrix pow(int n)`
Computes the n-th power of this matrix. An exception is thrown if this matrix is not square, since then the multiplication of a matrix with itself is not defined mathematically.
Parameters:
`n` - the exponent
Returns:
the n-th power of this matrix
Throws:
`IllegalArgumentException` - if this matrix is not square, or if n is negative and not invertible.
• getDominantEigenvalue

`public double getDominantEigenvalue()`
Returns the dominant eigenvalue of this matrix with an error `EPSILON`. The method implements the power iteration and works if this matrix has a real-valued dominant eigenvalue. According to the Perron-Frobenius theorem a sufficient condition for this is the matrix being irreducible, for instance being the adjacency matrix of a strongly connected graph where any node is reachable from every other node. If the power iteration does not converge, this method returns the maximum real part of all eigenvalues.
Returns:
the dominant eigenvalue of this matrix with an error `EPSILON`
• getDominantEigenvalue

`public double getDominantEigenvalue(double error)`
Returns the dominant eigenvalue of this matrix with the specified error of approximation. The method implements the power iteration and works if this matrix has a real-valued dominant eigenvalue. According to the Perron-Frobenius theorem a sufficient condition for this is the matrix being irreducible, for instance being the adjacency matrix of a strongly connected graph where any node is reachable from every other node. If the power iteration does not converge, this method returns the maximum real part of all eigenvalues.
Parameters:
`error` - maximum error of approximation
Returns:
the dominant eigenvalue of this matrix with the specified error of approximation
• getDominantEigenvector

`public double[] getDominantEigenvector()`
Returns an eigenvector associated to the dominant eigenvalue of this matrix with the error `EPSILON` of approximation. It invokes the method `getDominantEigenvalue()`, for more details see there.
Returns:
an eigenvector associated to the dominant eigenvalue of this matrix with an error `EPSILON`
• getDominantEigenvector

`public double[] getDominantEigenvector(double error)`
Returns an eigenvector associated to the dominant eigenvalue of this matrix with the specified error of approximation. It invokes the method `getDominantEigenvalue(double)`, for more details see there.
Parameters:
`error` - maximum error of approximation
Returns:
an eigenvector associated to the dominant eigenvalue of this matrix with the specified error of approximation
• getImagEigenvalues

`public double[] getImagEigenvalues()`
Returns an array consisting of the imaginary parts of the eigenvalues of this matrix. This method obtains its result from the `eigenvalue decomposition` of this matrix.
Returns:
an array of the imaginary parts of the eigenvalues of this matrix
Throws:
`IllegalArgumentException` - if this matrix is not square
`EigenvalueDecomposition.getImagEigenvalues()`
• getEigenvectors

`public Matrix getEigenvectors()`
Returns a matrix whose columns are the eigenvectors of this matrix. This method obtains its result from the `eigenvalue decomposition` of this matrix.
Returns:
an array of the real parts of the eigenvalues of this matrix
Throws:
`IllegalArgumentException` - if this matrix is not square
`EigenvalueDecomposition.getV()`

`public Matrix adjugate()`
Returns the adjugate of this matrix. An exception is thrown if this matrix is not square, since then the adjugate is not defined mathematically. For a definition of the adjugate see http://en.wikipedia.org/wiki/Adjugate_matrix
Returns:
Throws:
`IllegalArgumentException` - if the matrix is not square
• inverse

`public Matrix inverse()`
Returns the inverse of this matrix. An exception is thrown if this matrix is not invertible.
Returns:
the inverse of this matrix
Throws:
`IllegalArgumentException` - if the matrix is not invertible
• cofactor

```public double cofactor(int i,
int j)```
Returns the cofactor Cij = (-1)i + j Mij of this matrix, where Mij denotes the minor. For a definition of the cofactor and the minor of a matrix, see http://en.wikipedia.org/wiki/Minor (linear algebra)
Parameters:
`i` - index of cofactor Cij
`j` - index of cofactor Cij
Returns:
the cofactor Cij
Throws:
`IllegalArgumentException` - if the matrix is not square
• transpose

`public Matrix transpose()`
Returns the transpose of this matrix.
Returns:
the transpose this matrix
• transposeInPlace

`public void transposeInPlace()`
Transposes this matrix in place, that is, without using additional space to create a new matrix. Evidently, the matrix has to be square in this case.
Throws:
`IllegalArgumentException` - if this matrix is not square
• trace

`public double trace()`
Returns the trace of this matrix.
Returns:
the trace of this matrix
Throws:
`IllegalArgumentException` - if this matrix is not square

`public Matrix add(Matrix b)`
Returns the sum of this matrix with the given matrix b.
Parameters:
`b` - the matrix to be added to this matrix
Returns:
the sum of this matrix and the input matrix b
• plus

`public Matrix plus(Matrix b)`
Returns the sum of this matrix with the given matrix b.
Parameters:
`b` - the matrix to be added to this matrix
Returns:
the sum of this matrix and the input matrix b
• negative

`public Matrix negative()`
Returns the negative of this matrix.
Returns:
the negative of this matrix
• minus

`public Matrix minus(Matrix b)`
Returns the difference of this matrix with the given matrix b.
Parameters:
`b` - the matrix to be subtracted from this matrix
Returns:
the difference of this matrix and the input matrix b
• minus

```public static double[] minus(double[] v,
double[] w)```
Returns the subtraction of the vectors v and w.
Parameters:
`v` - a vector
`w` - a vector
Returns:
the difference vector v - w
Throws:
`IllegalArgumentException` - if number of entries of v and w differ
• times

`public Matrix times(Matrix b)`
Returns the (right) product of this matrix with the given matrix b.
Parameters:
`b` - the matrix to multiply this matrix from right
Returns:
the right product of this matrix and the input matrix b
Throws:
`IllegalArgumentException` - if number of columns of this matrix is different from the number of rows of b
• times

`public double[] times(double[] v)`
Returns the (right) product of this matrix with the given column vector v.
Parameters:
`v` - the column vector to multiply this matrix from right
Returns:
the right product of this matrix and the input vector v
Throws:
`IllegalArgumentException` - if number of columns of this matrix is different from the number of rows of v
• multiply

```public static double[] multiply(double a,
double[] v)```
Returns the product a*v.
Parameters:
`a` - a constant
`v` - a vector
Returns:
the product a*v
• multiply

```public static double multiply(double[] v,
double[] w)```
Returns the scalar product of the vectors v and w.
Parameters:
`v` - a row vector
`w` - a column vector
Returns:
the scalar product of the vectors v and w
Throws:
`IllegalArgumentException` - if number of entries of v and w differ
• tensor

`public static Matrix tensor(Matrix[] a)`
Returns the tensor product of the matrices a[0], a[1], ..., a[n-1], i.e., a[0] ⊗ a[1] ... a[n-2] ⊗ a[n-1].
Parameters:
`a` - array of several complex matrices a[0], a[1], ..., a[n-1]
Returns:
the tensor product a[n-1] ⊗ a[n-2] ⊗ ... ⊗ a[1] ⊗ a[0]
Throws:
`IllegalArgumentException` - if one of the matrices is empty
• tensor

`public static double[][] tensor(double[][][] a)`
Returns the tensor product of the matrices a[0], a[1], ..., a[n-1], i.e., a[0] ⊗ a[1] ... a[n-2] ⊗ a[n-1].
Parameters:
`a` - array of several complex matrices a[0], a[1], ..., a[n-1]
Returns:
the tensor product a[n-1] ⊗ a[n-2] ⊗ ... ⊗ a[1] ⊗ a[0]
Throws:
`IllegalArgumentException` - if one of the matrices is empty
• solve

`public Matrix solve(Matrix b)`
This method solves the n linear equation Ax = b, where A is this matrix and b the given vector. The method applies the Gaussian algorithm.
Parameters:
`b` - vector
Returns:
the solution vector x of Ax = b
Throws:
`IllegalArgumentException` - if b is not an appropriate column vector
• decomposeQR

`public Matrix[] decomposeQR()`
Returns the QR decomposition of this matrix as a pair of matrices. Here A = QR where A is this matrix, Q is an orthogonal matrix and R an upper triangular matrix.
Returns:
an array [Q,R] such that A = QR
Throws:
`IllegalArgumentException` - if this matrix has more columns than rows.
• toHTML

```public String toHTML(String align,
boolean showZeros)```
Returns a String representation of this matrix as an HTML table where each entry is aligned according to the specified value. The possible values are "left", "center", "right" (in case insensitive manner). If the specified string has another value, it is set internally to the default value "center".
Parameters:
`align` - the alignment of each matrix entry, either "left", "center", or "right"
`showZeros` - flag whether zeros in the matrix are to be displayed
Returns:
a String representation of this matrix as an HTML table.
• toHTML

`public String toHTML(String align)`
Returns a String representation of this matrix as an HTML table where each entry is aligned according to the specified value. The possible values are "left", "center", "right" (in case-insensitive manner). If the specified string has another value, it is set internally to the default value "center".
Parameters:
`align` - the alignment of each matrix entry, either "left", "center", or "right"
Returns:
a String representation of this matrix as an HTML table.
• toHTML

`public String toHTML()`
Returns a String representation of this matrix as an HTML table.
Returns:
a String representation of this matrix as an HTML table.
• toString

`public String toString()`
Returns a String representation of this matrix.
Overrides:
`toString` in class `Object`
Returns:
a string representation of this matrix
• getNorm

`public static double getNorm(double[] v)`
Returns the norm |v| of the vector v. This method computes the norm without unnecessary overflow or underflow.
Parameters:
`v` - a vector
Returns:
the norm |v| of the vector v
• createZero

```public static Matrix createZero(int m,
int n)```
Returns the zero (m × n) matrix.
Parameters:
`m` - the numbers of rows
`n` - the number of columns
Returns:
the zero (m × n) matrix
• createIdentity

`public static Matrix createIdentity(int n)`
This method creates an (n x n) unity matrix. I.e., a square matrix whose diagonal entries are 1's, and all other entries are 0.
Parameters:
`n` - the number of rows and columns
Returns:
the (n x n) unity matrix