Matrix (ph-matrix 9.5.5 API)

java.lang.Object
- com.helger.matrix.Matrix

All Implemented Interfaces:

com.helger.commons.lang.ICloneable<Matrix>, Serializable
```
public class Matrix
extends Object
implements Serializable, com.helger.commons.lang.ICloneable<Matrix>
```
Jama = Java Matrix class.
The Java Matrix Class provides the fundamental operations of numerical linear algebra. Various constructors create Matrices from two dimensional arrays of double precision floating point numbers. Various "gets" and "sets" provide access to submatrices and matrix elements. Several methods implement basic matrix arithmetic, including matrix addition and multiplication, matrix norms, and element-by-element array operations. Methods for reading and printing matrices are also included. All the operations in this version of the Matrix Class involve real matrices. Complex matrices may be handled in a future version.

Five fundamental matrix decompositions, which consist of pairs or triples of matrices, permutation vectors, and the like, produce results in five decomposition classes. These decompositions are accessed by the Matrix class to compute solutions of simultaneous linear equations, determinants, inverses and other matrix functions. The five decompositions are:
- Cholesky Decomposition of symmetric, positive definite matrices.
- LU Decomposition of rectangular matrices.
- QR Decomposition of rectangular matrices.
- Singular Value Decomposition of rectangular matrices.
- Eigenvalue Decomposition of both symmetric and nonsymmetric square matrices.
Example of use:
Solve a linear system A x = b and compute the residual norm, ||b - A x||.
```
 double [] [] vals = { { 1., 2., 3 }, { 4., 5., 6. }, { 7., 8., 10. } };
 Matrix A = new Matrix (vals);
 Matrix b = Matrix.random (3, 1);
 Matrix x = A.solve (b);
 Matrix r = A.times (x).minus (b);
 double rnorm = r.normInf ();
 
```
Version:

5 August 1998

Author:

The MathWorks, Inc. and the National Institute of Standards and Technology.

See Also:

Serialized Form

Constructor Summary

Constructors
Constructor and Description
`Matrix(double[] aVals, int nRows)` Construct a matrix from a one-dimensional packed array
`Matrix(int nRows, int nCols)` Construct an nRows-by-nCols matrix of zeros.
`Matrix(int nRows, int nCols, double dValue)` Construct an nRows-by-nCols constant matrix.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`Matrix`	`arrayLeftDivide(Matrix aMatrix)` Element-by-element left division, C = B.
`Matrix`	`arrayLeftDivideEquals(Matrix aMatrix)` Element-by-element left division in place, A = B.
`Matrix`	`arrayRightDivide(Matrix aMatrix)` Element-by-element right division, C = A.
`Matrix`	`arrayRightDivideEquals(Matrix aMatrix)` Element-by-element right division in place, A = A.
`Matrix`	`arrayTimes(Matrix aMatrix)` Element-by-element multiplication, C = A.
`Matrix`	`arrayTimesEquals(Matrix aMatrix)` Element-by-element multiplication in place, A = A.
`CholeskyDecomposition`	`chol()` Cholesky Decomposition
`double`	`cond()` Matrix condition (2 norm)
`static Matrix`	`constructWithCopy(double[][] aArray)` Construct a matrix from a copy of a 2-D array.
`double`	`det()` Matrix determinant
`EigenvalueDecomposition`	`eig()` Eigenvalue Decomposition
`boolean`	`equals(Object o)`
`double`	`get(int nRow, int nCol)` Get a single element.
`double[][]`	`getArrayCopy()` Copy the internal two-dimensional array.
`Matrix`	`getClone()`
`int`	`getColumnDimension()` Get column dimension.
`double[]`	`getColumnPackedCopy()` Make a one-dimensional column packed copy of the internal array.
`Matrix`	`getMatrix(int[] aRows, int[] aCols)` Get a submatrix.
`Matrix`	`getMatrix(int[] aRows, int nStartColumnIndex, int nEndColumnIndex)` Get a submatrix.
`Matrix`	`getMatrix(int nStartRowIndex, int nEndRowIndex, int[] aCols)` Get a submatrix.
`Matrix`	`getMatrix(int nStartRowIndex, int nEndRowIndex, int nStartColumnIndex, int nEndColumnIndex)` Get a submatrix.
`int`	`getRowDimension()` Get row dimension.
`double[]`	`getRowPackedCopy()` Make a one-dimensional row packed copy of the internal array.
`int`	`hashCode()`
`static Matrix`	`identity(int nRows, int nCols)` Generate identity matrix
`double[][]`	`internalGetArray()` Access the internal two-dimensional array.
`Matrix`	`inverse()` Matrix inverse or pseudoinverse
`boolean`	`isSymmetrical()`
`LUDecomposition`	`lu()` LU Decomposition
`Matrix`	`minus(Matrix aMatrix)` C = A - B
`Matrix`	`minusEquals(Matrix aMatrix)` A = A - B
`double`	`norm1()` One norm
`double`	`norm2()` Two norm
`double`	`normF()` Frobenius norm
`double`	`normInf()` Infinity norm
`Matrix`	`plus(Matrix aMatrix)` C = A + B
`Matrix`	`plusEquals(Matrix aMatrix)` A = A + B
`void`	`print(PrintWriter aPW, int nWidth, int nFractionDigits)` Print the matrix to the output stream.
`void`	`print(PrintWriter aPW, NumberFormat aFormat, int nWidth)` Print the matrix to the output stream.
`QRDecomposition`	`qr()` QR Decomposition
`static Matrix`	`random(int nRows, int nCols)` Generate matrix with random elements
`int`	`rank()` Matrix rank
`static Matrix`	`read(Reader aReader)` Read a matrix from a stream.
`void`	`set(int nRow, int nCol, double dValue)` Set a single element.
`void`	`setMatrix(int[] aRows, int[] aCols, Matrix aMatrix)` Set a submatrix.
`void`	`setMatrix(int[] aRows, int nStartColumnIndex, int nEndColumnIndex, Matrix aMatrix)` Set a submatrix.
`void`	`setMatrix(int nStartRowIndex, int nEndRowIndex, int[] aCols, Matrix aMatrix)` Set a submatrix.
`void`	`setMatrix(int nStartRowIndex, int nEndRowIndex, int nStartColumnIndex, int nEndColumnIndex, Matrix aMatrix)` Set a submatrix.
`Matrix`	`solve(Matrix aMatrix)` Solve A*X = B
`Matrix`	`solveTranspose(Matrix aMatrix)` Solve XA = B, which is also A'X' = B'
`SingularValueDecomposition`	`svd()` Singular Value Decomposition
`Matrix`	`times(double s)` Multiply a matrix by a scalar, C = s*A
`Matrix`	`times(Matrix aMatrix)` Linear algebraic matrix multiplication, A * B
`Matrix`	`timesEquals(double s)` Multiply a matrix by a scalar in place, A = s*A
`double`	`trace()` Matrix trace.
`Matrix`	`transpose()` Matrix transpose.
`Matrix`	`uminus()` Unary minus

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail
- Matrix
```
public Matrix(@Nonnegative
              int nRows,
              @Nonnegative
              int nCols)
```
  Construct an nRows-by-nCols matrix of zeros.
  
  Parameters:
  
  nRows - Number of rows.
  
  nCols - Number of columns.
- Matrix
```
public Matrix(@Nonnegative
              int nRows,
              @Nonnegative
              int nCols,
              double dValue)
```
  Construct an nRows-by-nCols constant matrix.
  
  Parameters:
  
  nRows - Number of rows.
  
  nCols - Number of columns.
  
  dValue - Fill the matrix with this scalar value.
- Matrix
```
public Matrix(@Nonnull
              double[] aVals,
              @Nonnegative
              int nRows)
```
  Construct a matrix from a one-dimensional packed array
  
  Parameters:
  
  aVals - One-dimensional array of doubles, packed by columns (ala Fortran).
  
  nRows - Number of rows.
  
  Throws:
  
  IllegalArgumentException - Array length must be a multiple of nRows.

Method Detail

constructWithCopy
```
@Nonnull
public static Matrix constructWithCopy(@Nonnull
                                                 double[][] aArray)
```
Construct a matrix from a copy of a 2-D array.

Parameters:

aArray - Two-dimensional array of doubles.

Returns:

The new matrix

Throws:

IllegalArgumentException - All rows must have the same length

getClone
```
@Nonnull
 @ReturnsMutableCopy
public Matrix getClone()
```
Specified by:

getClone in interface com.helger.commons.lang.ICloneable<Matrix>

Returns:

a deep copy of a matrix

internalGetArray
```
@Nonnull
public double[][] internalGetArray()
```
Access the internal two-dimensional array.

Returns:

Pointer to the two-dimensional array of matrix elements.

getArrayCopy
```
@Nonnull
 @ReturnsMutableCopy
public double[][] getArrayCopy()
```
Copy the internal two-dimensional array.

Returns:

Two-dimensional array copy of matrix elements.

getColumnPackedCopy
```
@Nonnull
public double[] getColumnPackedCopy()
```
Make a one-dimensional column packed copy of the internal array.

Returns:

Matrix elements packed in a one-dimensional array by columns.

getRowPackedCopy
```
@Nonnull
public double[] getRowPackedCopy()
```
Make a one-dimensional row packed copy of the internal array.

Returns:

Matrix elements packed in a one-dimensional array by rows.

getRowDimension
```
@Nonnegative
public int getRowDimension()
```
Get row dimension.

Returns:

nRows, the number of rows.

getColumnDimension
```
@Nonnegative
public int getColumnDimension()
```
Get column dimension.

Returns:

nCols, the number of columns.

isSymmetrical
```
public boolean isSymmetrical()
```
Returns:

true if the matrix is symmetrical, meaning number of rows and columns is identical.

get

public double get(@Nonnegative
                  int nRow,
                  @Nonnegative
                  int nCol)

Get a single element.

Parameters:: nRow - Row index.; nCol - Column index.
Returns:: A(nRow,nCol)

getMatrix

@Nonnull
 @ReturnsMutableCopy
public Matrix getMatrix(@Nonnegative
                                                        int nStartRowIndex,
                                                        @Nonnegative
                                                        int nEndRowIndex,
                                                        @Nonnegative
                                                        int nStartColumnIndex,
                                                        @Nonnegative
                                                        int nEndColumnIndex)

Get a submatrix.

Parameters:: nStartRowIndex - Initial row index; nEndRowIndex - Final row index; nStartColumnIndex - Initial column index; nEndColumnIndex - Final column index
Returns:: Matrix(nStartRowIndex:nEndRowIndex,nStartColumnIndex: nEndColumnIndex )
Throws:: ArrayIndexOutOfBoundsException - Submatrix indices

getMatrix

@Nonnull
 @ReturnsMutableCopy
public Matrix getMatrix(@Nonnull
                                                        int[] aRows,
                                                        @Nonnull
                                                        int[] aCols)

Get a submatrix.

Parameters:: aRows - Array of row indices.; aCols - Array of column indices.
Returns:: Matrix(aRows(:),aCols(:))
Throws:: ArrayIndexOutOfBoundsException - Submatrix indices

getMatrix

@Nonnull
 @ReturnsMutableCopy
public Matrix getMatrix(@Nonnegative
                                                        int nStartRowIndex,
                                                        @Nonnegative
                                                        int nEndRowIndex,
                                                        @Nonnull
                                                        int[] aCols)

Get a submatrix.

Parameters:: nStartRowIndex - Initial row index; nEndRowIndex - Final row index; aCols - Array of column indices.
Returns:: Matrix(nStartRowIndex:nEndRowIndex,aCols(:))
Throws:: ArrayIndexOutOfBoundsException - Submatrix indices

getMatrix

@Nonnull
 @ReturnsMutableCopy
public Matrix getMatrix(@Nonnull
                                                        int[] aRows,
                                                        @Nonnegative
                                                        int nStartColumnIndex,
                                                        @Nonnegative
                                                        int nEndColumnIndex)

Get a submatrix.

Parameters:: aRows - Array of row indices.; nStartColumnIndex - Initial column index; nEndColumnIndex - Final column index
Returns:: Matrix(aRows(:),nStartColumnIndex:nEndColumnIndex)
Throws:: ArrayIndexOutOfBoundsException - Submatrix indices

set

public void set(@Nonnegative
                int nRow,
                @Nonnegative
                int nCol,
                double dValue)

Set a single element.

Parameters:: nRow - Row index.; nCol - Column index.; dValue - A(nRow,nCol).

setMatrix

public void setMatrix(@Nonnegative
                      int nStartRowIndex,
                      @Nonnegative
                      int nEndRowIndex,
                      @Nonnegative
                      int nStartColumnIndex,
                      @Nonnegative
                      int nEndColumnIndex,
                      @Nonnull
                      Matrix aMatrix)

Set a submatrix.

Parameters:: nStartRowIndex - Initial row index; nEndRowIndex - Final row index; nStartColumnIndex - Initial column index; nEndColumnIndex - Final column index; aMatrix - Matrix(nStartRowIndex:nEndRowIndex,nStartColumnIndex:nEndColumnIndex )
Throws:: ArrayIndexOutOfBoundsException - Submatrix indices

setMatrix

public void setMatrix(@Nonnull
                      int[] aRows,
                      @Nonnull
                      int[] aCols,
                      @Nonnull
                      Matrix aMatrix)

Set a submatrix.

Parameters:: aRows - Array of row indices.; aCols - Array of column indices.; aMatrix - Matrix(aRows(:),aCols(:))
Throws:: ArrayIndexOutOfBoundsException - Submatrix indices

setMatrix

public void setMatrix(@Nonnull
                      int[] aRows,
                      @Nonnegative
                      int nStartColumnIndex,
                      @Nonnegative
                      int nEndColumnIndex,
                      @Nonnull
                      Matrix aMatrix)

Set a submatrix.

Parameters:: aRows - Array of row indices.; nStartColumnIndex - Initial column index; nEndColumnIndex - Final column index; aMatrix - Matrix(aRows(:),nStartColumnIndex:nEndColumnIndex
Throws:: ArrayIndexOutOfBoundsException - Submatrix indices

setMatrix

public void setMatrix(@Nonnegative
                      int nStartRowIndex,
                      @Nonnegative
                      int nEndRowIndex,
                      @Nonnull
                      int[] aCols,
                      @Nonnull
                      Matrix aMatrix)

Set a submatrix.

Parameters:: nStartRowIndex - Initial row index; nEndRowIndex - Final row index; aCols - Array of column indices.; aMatrix - Matrix(nStartRowIndex:nEndRowIndex,aCols(:))
Throws:: ArrayIndexOutOfBoundsException - Submatrix indices

transpose

@Nonnull
 @ReturnsMutableCopy
 @CheckReturnValue
public Matrix transpose()

Matrix transpose.

Returns:: A'

norm1
```
public double norm1()
```
One norm

Returns:

maximum column sum.

norm2
```
public double norm2()
```
Two norm

Returns:

maximum singular value.

normInf
```
public double normInf()
```
Infinity norm

Returns:

maximum row sum.

normF
```
public double normF()
```
Frobenius norm

Returns:

sqrt of sum of squares of all elements.

uminus

@Nonnull
 @ReturnsMutableCopy
public Matrix uminus()

Unary minus

Returns:: -A

plus

@Nonnull
 @ReturnsMutableCopy
public Matrix plus(@Nonnull
                                                   Matrix aMatrix)

C = A + B

Parameters:: aMatrix - another matrix
Returns:: A + B

plusEquals

@Nonnull
public Matrix plusEquals(@Nonnull
                                   Matrix aMatrix)

A = A + B

Parameters:: aMatrix - another matrix
Returns:: this

minus

@Nonnull
 @ReturnsMutableCopy
public Matrix minus(@Nonnull
                                                    Matrix aMatrix)

C = A - B

Parameters:: aMatrix - another matrix
Returns:: A - B

minusEquals

@Nonnull
public Matrix minusEquals(@Nonnull
                                    Matrix aMatrix)

A = A - B

Parameters:: aMatrix - another matrix
Returns:: this

arrayTimes

@Nonnull
 @ReturnsMutableCopy
public Matrix arrayTimes(@Nonnull
                                                         Matrix aMatrix)

Element-by-element multiplication, C = A.*B

Parameters:: aMatrix - another matrix
Returns:: A.*B

arrayTimesEquals

@Nonnull
public Matrix arrayTimesEquals(@Nonnull
                                         Matrix aMatrix)

Element-by-element multiplication in place, A = A.*B

Parameters:: aMatrix - another matrix
Returns:: this

arrayRightDivide

@Nonnull
 @ReturnsMutableCopy
public Matrix arrayRightDivide(@Nonnull
                                                               Matrix aMatrix)

Element-by-element right division, C = A./B

Parameters:: aMatrix - another matrix
Returns:: A./B

arrayRightDivideEquals

@Nonnull
public Matrix arrayRightDivideEquals(@Nonnull
                                               Matrix aMatrix)

Element-by-element right division in place, A = A./B

Parameters:: aMatrix - another matrix
Returns:: this

arrayLeftDivide

@Nonnull
 @ReturnsMutableCopy
public Matrix arrayLeftDivide(@Nonnull
                                                              Matrix aMatrix)

Element-by-element left division, C = B.\A

Parameters:: aMatrix - another matrix
Returns:: B.\A

arrayLeftDivideEquals

@Nonnull
public Matrix arrayLeftDivideEquals(@Nonnull
                                              Matrix aMatrix)

Element-by-element left division in place, A = B.\A

Parameters:: aMatrix - another matrix
Returns:: this

times
```
@Nonnull
 @ReturnsMutableCopy
public Matrix times(double s)
```
Multiply a matrix by a scalar, C = s*A

Parameters:

s - scalar

Returns:

s*A

timesEquals
```
@Nonnull
public Matrix timesEquals(double s)
```
Multiply a matrix by a scalar in place, A = s*A

Parameters:

s - scalar

Returns:

this

times

@Nonnull
 @ReturnsMutableCopy
public Matrix times(@Nonnull
                                                    Matrix aMatrix)

Linear algebraic matrix multiplication, A * B

Parameters:: aMatrix - another matrix
Returns:: Matrix product, A * B
Throws:: IllegalArgumentException - Matrix inner dimensions must agree.

lu

@Nonnull
 @ReturnsMutableCopy
public LUDecomposition lu()

LU Decomposition

Returns:: LUDecomposition
See Also:: LUDecomposition

qr

@Nonnull
 @ReturnsMutableCopy
public QRDecomposition qr()

QR Decomposition

Returns:: QRDecomposition
See Also:: QRDecomposition

chol
```
@Nonnull
 @ReturnsMutableCopy
public CholeskyDecomposition chol()
```
Cholesky Decomposition

Returns:

CholeskyDecomposition

See Also:

CholeskyDecomposition

svd
```
@Nonnull
 @ReturnsMutableCopy
public SingularValueDecomposition svd()
```
Singular Value Decomposition

Returns:

SingularValueDecomposition

See Also:

SingularValueDecomposition

eig
```
@Nonnull
 @ReturnsMutableCopy
public EigenvalueDecomposition eig()
```
Eigenvalue Decomposition

Returns:

EigenvalueDecomposition

See Also:

EigenvalueDecomposition

solve

@Nonnull
public Matrix solve(@Nonnull
                              Matrix aMatrix)

Solve A*X = B

Parameters:: aMatrix - right hand side
Returns:: solution if A is square, least squares solution otherwise

solveTranspose
```
@Nonnull
public Matrix solveTranspose(@Nonnull
                                       Matrix aMatrix)
```
Solve X*A = B, which is also A'*X' = B'

Parameters:

aMatrix - right hand side

Returns:

solution if A is square, least squares solution otherwise.

inverse
```
@Nonnull
public Matrix inverse()
```
Matrix inverse or pseudoinverse

Returns:

inverse(A) if A is square, pseudoinverse otherwise.

det
```
public double det()
```
Matrix determinant

Returns:

determinant

rank
```
public int rank()
```
Matrix rank

Returns:

effective numerical rank, obtained from SVD.

cond
```
public double cond()
```
Matrix condition (2 norm)

Returns:

ratio of largest to smallest singular value.

trace
```
public double trace()
```
Matrix trace.

Returns:

sum of the diagonal elements.

random

@Nonnull
 @ReturnsMutableCopy
public static Matrix random(@Nonnegative
                                                            int nRows,
                                                            @Nonnegative
                                                            int nCols)

Generate matrix with random elements

Parameters:: nRows - Number of rows.; nCols - Number of columns.
Returns:: An nRows-by-nCols matrix with uniformly distributed random elements.

identity

@Nonnull
 @ReturnsMutableCopy
public static Matrix identity(@Nonnegative
                                                              int nRows,
                                                              @Nonnegative
                                                              int nCols)

Generate identity matrix

Parameters:: nRows - Number of rows.; nCols - Number of columns.
Returns:: An nRows-by-nCols matrix with ones on the diagonal and zeros elsewhere.

print

public void print(@Nonnull
                  PrintWriter aPW,
                  @Nonnegative
                  int nWidth,
                  @Nonnegative
                  int nFractionDigits)

Print the matrix to the output stream. Line the elements up in columns with a Fortran-like 'Fw.d' style format.

Parameters:: aPW - Output stream.; nWidth - Column width.; nFractionDigits - Number of digits after the decimal.

print
```
public void print(@Nonnull
                  PrintWriter aPW,
                  @Nonnull
                  NumberFormat aFormat,
                  @Nonnegative
                  int nWidth)
```
Print the matrix to the output stream. Line the elements up in columns. Use the format object, and right justify within columns of width characters. Note that is the matrix is to be read back in, you probably will want to use a NumberFormat that is set to US Locale.

Parameters:

aPW - the output stream.

aFormat - A formatting object to format the matrix elements

nWidth - Column width.

See Also:

DecimalFormat.setDecimalFormatSymbols(java.text.DecimalFormatSymbols)

equals
```
public boolean equals(Object o)
```
Overrides:

equals in class Object

hashCode
```
public int hashCode()
```
Overrides:

hashCode in class Object

read
```
@Nonnull
public static Matrix read(@Nonnull @WillNotClose
                                    Reader aReader)
                             throws IOException
```
Read a matrix from a stream. The format is the same the print method, so printed matrices can be read back in (provided they were printed using US Locale). Elements are separated by whitespace, all the elements for each row appear on a single line, the last row is followed by a blank line.

Parameters:

aReader - the input stream.

Returns:

The read matrix

Throws:

IOException - In case of an I/O error

Class Matrix

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Matrix

Matrix

Matrix

Method Detail

constructWithCopy

getClone

internalGetArray

getArrayCopy

getColumnPackedCopy

getRowPackedCopy

getRowDimension

getColumnDimension

isSymmetrical

get

getMatrix

getMatrix

getMatrix

getMatrix

set

setMatrix

setMatrix

setMatrix

setMatrix

transpose

norm1

norm2

normInf

normF

uminus

plus

plusEquals

minus

minusEquals

arrayTimes

arrayTimesEquals

arrayRightDivide

arrayRightDivideEquals

arrayLeftDivide

arrayLeftDivideEquals

times

timesEquals

times

lu

qr

chol

svd

eig

solve

solveTranspose

inverse

det

rank

cond

trace

random

identity

print

print

equals

hashCode

read