org.apache.commons.math3.linear

## Class MatrixUtils

- java.lang.Object
- - 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 1244107 2012-02-14 16:17:55Z erans $

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `static Array2DRowRealMatrix` | `bigFractionMatrixToRealMatrix(FieldMatrix<BigFraction> m)` Convert a `FieldMatrix`/`BigFraction` matrix to a `RealMatrix`.
    `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 <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 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`

- - ### 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)

      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`.
      See Also:
        `createRealMatrix(int, int)`

    - #### createFieldMatrix

          public static <T extends FieldElement<T>> FieldMatrix<T> createFieldMatrix(T[][] data)

      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)

      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)

      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)

      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)

      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)

      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)

      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`.

    - #### checkMatrixIndex

          public static void checkMatrixIndex(AnyMatrix m,
                              int row,
                              int column)

      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)

      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)

      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)

      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)

      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)

      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)

      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)

      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)

      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:
        `IllegalArgumentException` - if the matrix and vector are not conformable
        `ArithmeticException` - there is a zero or near zero on the diagonal of rm

    - #### solveUpperTriangularSystem

          public static void solveUpperTriangularSystem(RealMatrix rm,
                                        RealVector b)

      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:
        `IllegalArgumentException` - if the matrix and vector are not conformable
        `ArithmeticException` - there is a zero or near zero on the diagonal of rm

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