org.apache.commons.math3.linear
Class MatrixUtils

java.lang.Object
  extended by org.apache.commons.math3.linear.MatrixUtils

public class MatrixUtils
extends Object

A collection of static methods that operate on or return matrices.

Version:
$Id: MatrixUtils.java 1449528 2013-02-24 19:06:20Z luc $

Field Summary
static RealMatrixFormat DEFAULT_FORMAT
          The default format for RealMatrix objects.
static RealMatrixFormat OCTAVE_FORMAT
          A format for RealMatrix objects compatible with octave.
 
Method Summary
static Array2DRowRealMatrix bigFractionMatrixToRealMatrix(FieldMatrix<BigFraction> m)
          Convert a FieldMatrix/BigFraction matrix to a RealMatrix.
static RealMatrix blockInverse(RealMatrix m, int splitIndex)
          Computes the inverse of the given matrix by splitting it into 4 sub-matrices.
static void checkAdditionCompatible(AnyMatrix left, AnyMatrix right)
          Check if matrices are addition compatible.
static void checkColumnIndex(AnyMatrix m, int column)
          Check if a column index is valid.
static void checkMatrixIndex(AnyMatrix m, int row, int column)
          Check if matrix indices are valid.
static void checkMultiplicationCompatible(AnyMatrix left, AnyMatrix right)
          Check if matrices are multiplication compatible
static void checkRowIndex(AnyMatrix m, int row)
          Check if a row index is valid.
static void checkSubMatrixIndex(AnyMatrix m, int[] selectedRows, int[] selectedColumns)
          Check if submatrix ranges indices are valid.
static void checkSubMatrixIndex(AnyMatrix m, int startRow, int endRow, int startColumn, int endColumn)
          Check if submatrix ranges indices are valid.
static void checkSubtractionCompatible(AnyMatrix left, AnyMatrix right)
          Check if matrices are subtraction compatible
static void checkSymmetric(RealMatrix matrix, double eps)
          Checks whether a matrix is symmetric.
static
<T extends FieldElement<T>>
FieldMatrix<T>
createColumnFieldMatrix(T[] columnData)
          Creates a column FieldMatrix using the data from the input array.
static RealMatrix createColumnRealMatrix(double[] columnData)
          Creates a column RealMatrix using the data from the input array.
static
<T extends FieldElement<T>>
FieldMatrix<T>
createFieldDiagonalMatrix(T[] diagonal)
          Returns a diagonal matrix with specified elements.
static
<T extends FieldElement<T>>
FieldMatrix<T>
createFieldIdentityMatrix(Field<T> field, int dimension)
          Returns dimension x dimension identity matrix.
static
<T extends FieldElement<T>>
FieldMatrix<T>
createFieldMatrix(Field<T> field, int rows, int columns)
          Returns a FieldMatrix with specified dimensions.
static
<T extends FieldElement<T>>
FieldMatrix<T>
createFieldMatrix(T[][] data)
          Returns a FieldMatrix whose entries are the the values in the the input array.
static
<T extends FieldElement<T>>
FieldVector<T>
createFieldVector(T[] data)
          Creates a FieldVector using the data from the input array.
static RealMatrix createRealDiagonalMatrix(double[] diagonal)
          Returns a diagonal matrix with specified elements.
static RealMatrix createRealIdentityMatrix(int dimension)
          Returns dimension x dimension identity matrix.
static RealMatrix createRealMatrix(double[][] data)
          Returns a RealMatrix whose entries are the the values in the the input array.
static RealMatrix createRealMatrix(int rows, int columns)
          Returns a RealMatrix with specified dimensions.
static RealVector createRealVector(double[] data)
          Creates a RealVector using the data from the input array.
static
<T extends FieldElement<T>>
FieldMatrix<T>
createRowFieldMatrix(T[] rowData)
          Create a row FieldMatrix using the data from the input array.
static RealMatrix createRowRealMatrix(double[] rowData)
          Create a row RealMatrix using the data from the input array.
static void deserializeRealMatrix(Object instance, String fieldName, ObjectInputStream ois)
          Deserialize a RealMatrix field in a class.
static void deserializeRealVector(Object instance, String fieldName, ObjectInputStream ois)
          Deserialize a RealVector field in a class.
static Array2DRowRealMatrix fractionMatrixToRealMatrix(FieldMatrix<Fraction> m)
          Convert a FieldMatrix/Fraction matrix to a RealMatrix.
static boolean isSymmetric(RealMatrix matrix, double eps)
          Checks whether a matrix is symmetric.
static void serializeRealMatrix(RealMatrix matrix, ObjectOutputStream oos)
          Serialize a RealMatrix.
static void serializeRealVector(RealVector vector, ObjectOutputStream oos)
          Serialize a RealVector.
static void solveLowerTriangularSystem(RealMatrix rm, RealVector b)
          Solve a system of composed of a Lower Triangular Matrix RealMatrix.
static void solveUpperTriangularSystem(RealMatrix rm, RealVector b)
          Solver a system composed of an Upper Triangular Matrix RealMatrix.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEFAULT_FORMAT

public static final RealMatrixFormat DEFAULT_FORMAT
The default format for RealMatrix objects.

Since:
3.1

OCTAVE_FORMAT

public static final RealMatrixFormat OCTAVE_FORMAT
A format for RealMatrix objects compatible with octave.

Since:
3.1
Method Detail

createRealMatrix

public static RealMatrix createRealMatrix(int rows,
                                          int columns)
Returns a RealMatrix with specified dimensions.

The type of matrix returned depends on the dimension. Below 212 elements (i.e. 4096 elements or 64×64 for a square matrix) which can be stored in a 32kB array, a Array2DRowRealMatrix instance is built. Above this threshold a BlockRealMatrix instance is built.

The matrix elements are all set to 0.0.

Parameters:
rows - number of rows of the matrix
columns - number of columns of the matrix
Returns:
RealMatrix with specified dimensions
See Also:
createRealMatrix(double[][])

createFieldMatrix

public static <T extends FieldElement<T>> FieldMatrix<T> createFieldMatrix(Field<T> field,
                                                                           int rows,
                                                                           int columns)
Returns a FieldMatrix with specified dimensions.

The type of matrix returned depends on the dimension. Below 212 elements (i.e. 4096 elements or 64×64 for a square matrix), a FieldMatrix instance is built. Above this threshold a BlockFieldMatrix instance is built.

The matrix elements are all set to field.getZero().

Type Parameters:
T - the type of the field elements
Parameters:
field - field to which the matrix elements belong
rows - number of rows of the matrix
columns - number of columns of the matrix
Returns:
FieldMatrix with specified dimensions
Since:
2.0
See Also:
createFieldMatrix(FieldElement[][])

createRealMatrix

public static RealMatrix createRealMatrix(double[][] data)
                                   throws NullArgumentException,
                                          DimensionMismatchException,
                                          NoDataException
Returns a RealMatrix whose entries are the the values in the the input array.

The type of matrix returned depends on the dimension. Below 212 elements (i.e. 4096 elements or 64×64 for a square matrix) which can be stored in a 32kB array, a Array2DRowRealMatrix instance is built. Above this threshold a BlockRealMatrix instance is built.

The input array is copied, not referenced.

Parameters:
data - input array
Returns:
RealMatrix containing the values of the array
Throws:
DimensionMismatchException - if data is not rectangular (not all rows have the same length).
NoDataException - if a row or column is empty.
NullArgumentException - if either data or data[0] is null.
DimensionMismatchException - if data is not rectangular.
See Also:
createRealMatrix(int, int)

createFieldMatrix

public static <T extends FieldElement<T>> FieldMatrix<T> createFieldMatrix(T[][] data)
                                                                throws DimensionMismatchException,
                                                                       NoDataException,
                                                                       NullArgumentException
Returns a FieldMatrix whose entries are the the values in the the input array.

The type of matrix returned depends on the dimension. Below 212 elements (i.e. 4096 elements or 64×64 for a square matrix), a FieldMatrix instance is built. Above this threshold a BlockFieldMatrix instance is built.

The input array is copied, not referenced.

Type Parameters:
T - the type of the field elements
Parameters:
data - input array
Returns:
a matrix containing the values of the array.
Throws:
DimensionMismatchException - if data is not rectangular (not all rows have the same length).
NoDataException - if a row or column is empty.
NullArgumentException - if either data or data[0] is null.
Since:
2.0
See Also:
createFieldMatrix(Field, int, int)

createRealIdentityMatrix

public static RealMatrix createRealIdentityMatrix(int dimension)
Returns dimension x dimension identity matrix.

Parameters:
dimension - dimension of identity matrix to generate
Returns:
identity matrix
Throws:
IllegalArgumentException - if dimension is not positive
Since:
1.1

createFieldIdentityMatrix

public static <T extends FieldElement<T>> FieldMatrix<T> createFieldIdentityMatrix(Field<T> field,
                                                                                   int dimension)
Returns dimension x dimension identity matrix.

Type Parameters:
T - the type of the field elements
Parameters:
field - field to which the elements belong
dimension - dimension of identity matrix to generate
Returns:
identity matrix
Throws:
IllegalArgumentException - if dimension is not positive
Since:
2.0

createRealDiagonalMatrix

public static RealMatrix createRealDiagonalMatrix(double[] diagonal)
Returns a diagonal matrix with specified elements.

Parameters:
diagonal - diagonal elements of the matrix (the array elements will be copied)
Returns:
diagonal matrix
Since:
2.0

createFieldDiagonalMatrix

public static <T extends FieldElement<T>> FieldMatrix<T> createFieldDiagonalMatrix(T[] diagonal)
Returns a diagonal matrix with specified elements.

Type Parameters:
T - the type of the field elements
Parameters:
diagonal - diagonal elements of the matrix (the array elements will be copied)
Returns:
diagonal matrix
Since:
2.0

createRealVector

public static RealVector createRealVector(double[] data)
                                   throws NoDataException,
                                          NullArgumentException
Creates a RealVector using the data from the input array.

Parameters:
data - the input data
Returns:
a data.length RealVector
Throws:
NoDataException - if data is empty.
NullArgumentException - if data is null.

createFieldVector

public static <T extends FieldElement<T>> FieldVector<T> createFieldVector(T[] data)
                                                                throws NoDataException,
                                                                       NullArgumentException,
                                                                       ZeroException
Creates a FieldVector using the data from the input array.

Type Parameters:
T - the type of the field elements
Parameters:
data - the input data
Returns:
a data.length FieldVector
Throws:
NoDataException - if data is empty.
NullArgumentException - if data is null.
ZeroException - if data has 0 elements

createRowRealMatrix

public static RealMatrix createRowRealMatrix(double[] rowData)
                                      throws NoDataException,
                                             NullArgumentException
Create a row RealMatrix using the data from the input array.

Parameters:
rowData - the input row data
Returns:
a 1 x rowData.length RealMatrix
Throws:
NoDataException - if rowData is empty.
NullArgumentException - if rowData is null.

createRowFieldMatrix

public static <T extends FieldElement<T>> FieldMatrix<T> createRowFieldMatrix(T[] rowData)
                                                                   throws NoDataException,
                                                                          NullArgumentException
Create a row FieldMatrix using the data from the input array.

Type Parameters:
T - the type of the field elements
Parameters:
rowData - the input row data
Returns:
a 1 x rowData.length FieldMatrix
Throws:
NoDataException - if rowData is empty.
NullArgumentException - if rowData is null.

createColumnRealMatrix

public static RealMatrix createColumnRealMatrix(double[] columnData)
                                         throws NoDataException,
                                                NullArgumentException
Creates a column RealMatrix using the data from the input array.

Parameters:
columnData - the input column data
Returns:
a columnData x 1 RealMatrix
Throws:
NoDataException - if columnData is empty.
NullArgumentException - if columnData is null.

createColumnFieldMatrix

public static <T extends FieldElement<T>> FieldMatrix<T> createColumnFieldMatrix(T[] columnData)
                                                                      throws NoDataException,
                                                                             NullArgumentException
Creates a column FieldMatrix using the data from the input array.

Type Parameters:
T - the type of the field elements
Parameters:
columnData - the input column data
Returns:
a columnData x 1 FieldMatrix
Throws:
NoDataException - if data is empty.
NullArgumentException - if columnData is null.

checkSymmetric

public static void checkSymmetric(RealMatrix matrix,
                                  double eps)
Checks whether a matrix is symmetric.

Parameters:
matrix - Matrix to check.
eps - Relative tolerance.
Throws:
NonSquareMatrixException - if the matrix is not square.
NonSymmetricMatrixException - if the matrix is not symmetric.
Since:
3.1

isSymmetric

public static boolean isSymmetric(RealMatrix matrix,
                                  double eps)
Checks whether a matrix is symmetric.

Parameters:
matrix - Matrix to check.
eps - Relative tolerance.
Returns:
true if matrix is symmetric.
Since:
3.1

checkMatrixIndex

public static void checkMatrixIndex(AnyMatrix m,
                                    int row,
                                    int column)
                             throws OutOfRangeException
Check if matrix indices are valid.

Parameters:
m - Matrix.
row - Row index to check.
column - Column index to check.
Throws:
OutOfRangeException - if row or column is not a valid index.

checkRowIndex

public static void checkRowIndex(AnyMatrix m,
                                 int row)
                          throws OutOfRangeException
Check if a row index is valid.

Parameters:
m - Matrix.
row - Row index to check.
Throws:
OutOfRangeException - if row is not a valid index.

checkColumnIndex

public static void checkColumnIndex(AnyMatrix m,
                                    int column)
                             throws OutOfRangeException
Check if a column index is valid.

Parameters:
m - Matrix.
column - Column index to check.
Throws:
OutOfRangeException - if column is not a valid index.

checkSubMatrixIndex

public static void checkSubMatrixIndex(AnyMatrix m,
                                       int startRow,
                                       int endRow,
                                       int startColumn,
                                       int endColumn)
                                throws NumberIsTooSmallException,
                                       OutOfRangeException
Check if submatrix ranges indices are valid. Rows and columns are indicated counting from 0 to n - 1.

Parameters:
m - Matrix.
startRow - Initial row index.
endRow - Final row index.
startColumn - Initial column index.
endColumn - Final column index.
Throws:
OutOfRangeException - if the indices are invalid.
NumberIsTooSmallException - if endRow < startRow or endColumn < startColumn.

checkSubMatrixIndex

public static void checkSubMatrixIndex(AnyMatrix m,
                                       int[] selectedRows,
                                       int[] selectedColumns)
                                throws NoDataException,
                                       NullArgumentException,
                                       OutOfRangeException
Check if submatrix ranges indices are valid. Rows and columns are indicated counting from 0 to n-1.

Parameters:
m - Matrix.
selectedRows - Array of row indices.
selectedColumns - Array of column indices.
Throws:
NullArgumentException - if selectedRows or selectedColumns are null.
NoDataException - if the row or column selections are empty (zero length).
OutOfRangeException - if row or column selections are not valid.

checkAdditionCompatible

public static void checkAdditionCompatible(AnyMatrix left,
                                           AnyMatrix right)
                                    throws MatrixDimensionMismatchException
Check if matrices are addition compatible.

Parameters:
left - Left hand side matrix.
right - Right hand side matrix.
Throws:
MatrixDimensionMismatchException - if the matrices are not addition compatible.

checkSubtractionCompatible

public static void checkSubtractionCompatible(AnyMatrix left,
                                              AnyMatrix right)
                                       throws MatrixDimensionMismatchException
Check if matrices are subtraction compatible

Parameters:
left - Left hand side matrix.
right - Right hand side matrix.
Throws:
MatrixDimensionMismatchException - if the matrices are not addition compatible.

checkMultiplicationCompatible

public static void checkMultiplicationCompatible(AnyMatrix left,
                                                 AnyMatrix right)
                                          throws DimensionMismatchException
Check if matrices are multiplication compatible

Parameters:
left - Left hand side matrix.
right - Right hand side matrix.
Throws:
DimensionMismatchException - if matrices are not multiplication compatible.

fractionMatrixToRealMatrix

public static Array2DRowRealMatrix fractionMatrixToRealMatrix(FieldMatrix<Fraction> m)
Convert a FieldMatrix/Fraction matrix to a RealMatrix.

Parameters:
m - Matrix to convert.
Returns:
the converted matrix.

bigFractionMatrixToRealMatrix

public static Array2DRowRealMatrix bigFractionMatrixToRealMatrix(FieldMatrix<BigFraction> m)
Convert a FieldMatrix/BigFraction matrix to a RealMatrix.

Parameters:
m - Matrix to convert.
Returns:
the converted matrix.

serializeRealVector

public static void serializeRealVector(RealVector vector,
                                       ObjectOutputStream oos)
                                throws IOException
Serialize a RealVector.

This method is intended to be called from within a private writeObject method (after a call to oos.defaultWriteObject()) in a class that has a RealVector field, which should be declared transient. This way, the default handling does not serialize the vector (the RealVector interface is not serializable by default) but this method does serialize it specifically.

The following example shows how a simple class with a name and a real vector should be written:


 public class NamedVector implements Serializable {

     private final String name;
     private final transient RealVector coefficients;

     // omitted constructors, getters ...

     private void writeObject(ObjectOutputStream oos) throws IOException {
         oos.defaultWriteObject();  // takes care of name field
         MatrixUtils.serializeRealVector(coefficients, oos);
     }

     private void readObject(ObjectInputStream ois) throws ClassNotFoundException, IOException {
         ois.defaultReadObject();  // takes care of name field
         MatrixUtils.deserializeRealVector(this, "coefficients", ois);
     }

 }
 

Parameters:
vector - real vector to serialize
oos - stream where the real vector should be written
Throws:
IOException - if object cannot be written to stream
See Also:
deserializeRealVector(Object, String, ObjectInputStream)

deserializeRealVector

public static void deserializeRealVector(Object instance,
                                         String fieldName,
                                         ObjectInputStream ois)
                                  throws ClassNotFoundException,
                                         IOException
Deserialize a RealVector field in a class.

This method is intended to be called from within a private readObject method (after a call to ois.defaultReadObject()) in a class that has a RealVector field, which should be declared transient. This way, the default handling does not deserialize the vector (the RealVector interface is not serializable by default) but this method does deserialize it specifically.

Parameters:
instance - instance in which the field must be set up
fieldName - name of the field within the class (may be private and final)
ois - stream from which the real vector should be read
Throws:
ClassNotFoundException - if a class in the stream cannot be found
IOException - if object cannot be read from the stream
See Also:
serializeRealVector(RealVector, ObjectOutputStream)

serializeRealMatrix

public static void serializeRealMatrix(RealMatrix matrix,
                                       ObjectOutputStream oos)
                                throws IOException
Serialize a RealMatrix.

This method is intended to be called from within a private writeObject method (after a call to oos.defaultWriteObject()) in a class that has a RealMatrix field, which should be declared transient. This way, the default handling does not serialize the matrix (the RealMatrix interface is not serializable by default) but this method does serialize it specifically.

The following example shows how a simple class with a name and a real matrix should be written:


 public class NamedMatrix implements Serializable {

     private final String name;
     private final transient RealMatrix coefficients;

     // omitted constructors, getters ...

     private void writeObject(ObjectOutputStream oos) throws IOException {
         oos.defaultWriteObject();  // takes care of name field
         MatrixUtils.serializeRealMatrix(coefficients, oos);
     }

     private void readObject(ObjectInputStream ois) throws ClassNotFoundException, IOException {
         ois.defaultReadObject();  // takes care of name field
         MatrixUtils.deserializeRealMatrix(this, "coefficients", ois);
     }

 }
 

Parameters:
matrix - real matrix to serialize
oos - stream where the real matrix should be written
Throws:
IOException - if object cannot be written to stream
See Also:
deserializeRealMatrix(Object, String, ObjectInputStream)

deserializeRealMatrix

public static void deserializeRealMatrix(Object instance,
                                         String fieldName,
                                         ObjectInputStream ois)
                                  throws ClassNotFoundException,
                                         IOException
Deserialize a RealMatrix field in a class.

This method is intended to be called from within a private readObject method (after a call to ois.defaultReadObject()) in a class that has a RealMatrix field, which should be declared transient. This way, the default handling does not deserialize the matrix (the RealMatrix interface is not serializable by default) but this method does deserialize it specifically.

Parameters:
instance - instance in which the field must be set up
fieldName - name of the field within the class (may be private and final)
ois - stream from which the real matrix should be read
Throws:
ClassNotFoundException - if a class in the stream cannot be found
IOException - if object cannot be read from the stream
See Also:
serializeRealMatrix(RealMatrix, ObjectOutputStream)

solveLowerTriangularSystem

public static void solveLowerTriangularSystem(RealMatrix rm,
                                              RealVector b)
                                       throws DimensionMismatchException,
                                              MathArithmeticException,
                                              NonSquareMatrixException
Solve a system of composed of a Lower Triangular Matrix RealMatrix.

This method is called to solve systems of equations which are of the lower triangular form. The matrix RealMatrix is assumed, though not checked, to be in lower triangular form. The vector RealVector is overwritten with the solution. The matrix is checked that it is square and its dimensions match the length of the vector.

Parameters:
rm - RealMatrix which is lower triangular
b - RealVector this is overwritten
Throws:
DimensionMismatchException - if the matrix and vector are not conformable
NonSquareMatrixException - if the matrix rm is not square
MathArithmeticException - if the absolute value of one of the diagonal coefficient of rm is lower than Precision.SAFE_MIN

solveUpperTriangularSystem

public static void solveUpperTriangularSystem(RealMatrix rm,
                                              RealVector b)
                                       throws DimensionMismatchException,
                                              MathArithmeticException,
                                              NonSquareMatrixException
Solver a system composed of an Upper Triangular Matrix RealMatrix.

This method is called to solve systems of equations which are of the lower triangular form. The matrix RealMatrix is assumed, though not checked, to be in upper triangular form. The vector RealVector is overwritten with the solution. The matrix is checked that it is square and its dimensions match the length of the vector.

Parameters:
rm - RealMatrix which is upper triangular
b - RealVector this is overwritten
Throws:
DimensionMismatchException - if the matrix and vector are not conformable
NonSquareMatrixException - if the matrix rm is not square
MathArithmeticException - if the absolute value of one of the diagonal coefficient of rm is lower than Precision.SAFE_MIN

blockInverse

public static RealMatrix blockInverse(RealMatrix m,
                                      int splitIndex)
Computes the inverse of the given matrix by splitting it into 4 sub-matrices.

Parameters:
m - Matrix whose inverse must be computed.
splitIndex - Index that determines the "split" line and column. The element corresponding to this index will part of the upper-left sub-matrix.
Returns:
the inverse of m.
Throws:
NonSquareMatrixException - if m is not square.


Copyright © 2003-2013 The Apache Software Foundation. All Rights Reserved.