Package org.apache.commons.math.linear

Class MatrixUtils

java.lang.Object
org.apache.commons.math.linear.MatrixUtils
public class MatrixUtils extends Object
A collection of static methods that operate on or return matrices.

  • Method Details

    • 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:

    • 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:

    • 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:
      IllegalArgumentException - if data is not rectangular (not all rows have the same length) or empty
      NullPointerException - if either data or data[0] is null
      See Also:

    • 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:
      RealMatrix containing the values of the array
      Throws:
      IllegalArgumentException - if data is not rectangular (not all rows have the same length) or empty
      NullPointerException - if either data or data[0] is null
      Since:
      2.0
      See Also:

    • 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

    • createBigIdentityMatrix

      @Deprecated public static BigMatrix createBigIdentityMatrix(int dimension)
      Deprecated.
      since 2.0, replaced by createFieldIdentityMatrix(Field, int)
      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

    • 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

    • createBigMatrix

      @Deprecated public static BigMatrix createBigMatrix(double[][] data)
      Deprecated.
      since 2.0 replaced by createFieldMatrix(FieldElement[][])
      Returns a BigMatrix whose entries are the the values in the the input array. The input array is copied, not referenced.
      Parameters:
      data - input array
      Returns:
      RealMatrix containing the values of the array
      Throws:
      IllegalArgumentException - if data is not rectangular (not all rows have the same length) or empty
      NullPointerException - if data is null

    • createBigMatrix

      @Deprecated public static BigMatrix createBigMatrix(BigDecimal[][] data)
      Deprecated.
      since 2.0 replaced by createFieldMatrix(FieldElement[][])
      Returns a BigMatrix whose entries are the the values in the the input array. The input array is copied, not referenced.
      Parameters:
      data - input array
      Returns:
      RealMatrix containing the values of the array
      Throws:
      IllegalArgumentException - if data is not rectangular (not all rows have the same length) or empty
      NullPointerException - if data is null

    • createBigMatrix

      @Deprecated public static BigMatrix createBigMatrix(BigDecimal[][] data, boolean copyArray)
      Deprecated.
      since 2.0 replaced by createFieldMatrix(FieldElement[][])
      Returns a BigMatrix whose entries are the the values in the the input array.

      If an array is built specially in order to be embedded in a BigMatrix and not used directly, the copyArray may be set to falseinvalid input: '<'/code. This will prevent the copying and improve performance as no new array will be built and no data will be copied.

      Parameters:
      data - data for new matrix
      copyArray - if true, the input array will be copied, otherwise it will be referenced
      Returns:
      BigMatrix containing the values of the array
      Throws:
      IllegalArgumentException - if data is not rectangular (not all rows have the same length) or empty
      NullPointerException - if data is null
      See Also:

    • createBigMatrix

      @Deprecated public static BigMatrix createBigMatrix(String[][] data)
      Deprecated.
      since 2.0 replaced by createFieldMatrix(FieldElement[][])
      Returns a BigMatrix whose entries are the the values in the the input array. The input array is copied, not referenced.
      Parameters:
      data - input array
      Returns:
      RealMatrix containing the values of the array
      Throws:
      IllegalArgumentException - if data is not rectangular (not all rows have the same length) or empty
      NullPointerException - if data is null

    • 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:
      IllegalArgumentException - if data is empty
      NullPointerException - if datais 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:
      IllegalArgumentException - if data is empty
      NullPointerException - if datais null

    • createRowRealMatrix

      public static RealMatrix createRowRealMatrix(double[] rowData)
      Creates a row RealMatrix using the data from the input array.
      Parameters:
      rowData - the input row data
      Returns:
      a 1 x rowData.length RealMatrix
      Throws:
      IllegalArgumentException - if rowData is empty
      NullPointerException - if rowDatais null

    • createRowFieldMatrix

      public static <T extends FieldElement<T>> FieldMatrix<T> createRowFieldMatrix(T[] rowData)
      Creates 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:
      IllegalArgumentException - if rowData is empty
      NullPointerException - if rowDatais null

    • createRowBigMatrix

      @Deprecated public static BigMatrix createRowBigMatrix(double[] rowData)
      Deprecated.
      since 2.0 replaced by createRowFieldMatrix(FieldElement[])
      Creates a row BigMatrix using the data from the input array.
      Parameters:
      rowData - the input row data
      Returns:
      a 1 x rowData.length BigMatrix
      Throws:
      IllegalArgumentException - if rowData is empty
      NullPointerException - if rowDatais null

    • createRowBigMatrix

      @Deprecated public static BigMatrix createRowBigMatrix(BigDecimal[] rowData)
      Deprecated.
      since 2.0 replaced by createRowFieldMatrix(FieldElement[])
      Creates a row BigMatrix using the data from the input array.
      Parameters:
      rowData - the input row data
      Returns:
      a 1 x rowData.length BigMatrix
      Throws:
      IllegalArgumentException - if rowData is empty
      NullPointerException - if rowDatais null

    • createRowBigMatrix

      @Deprecated public static BigMatrix createRowBigMatrix(String[] rowData)
      Deprecated.
      since 2.0 replaced by createRowFieldMatrix(FieldElement[])
      Creates a row BigMatrix using the data from the input array.
      Parameters:
      rowData - the input row data
      Returns:
      a 1 x rowData.length BigMatrix
      Throws:
      IllegalArgumentException - if rowData is empty
      NullPointerException - if rowDatais 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:
      IllegalArgumentException - if columnData is empty
      NullPointerException - if columnDatais 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:
      IllegalArgumentException - if columnData is empty
      NullPointerException - if columnDatais null

    • createColumnBigMatrix

      @Deprecated public static BigMatrix createColumnBigMatrix(double[] columnData)
      Deprecated.
      since 2.0 replaced by createColumnFieldMatrix(FieldElement[])
      Creates a column BigMatrix using the data from the input array.
      Parameters:
      columnData - the input column data
      Returns:
      a columnData x 1 BigMatrix
      Throws:
      IllegalArgumentException - if columnData is empty
      NullPointerException - if columnDatais null

    • createColumnBigMatrix

      @Deprecated public static BigMatrix createColumnBigMatrix(BigDecimal[] columnData)
      Deprecated.
      since 2.0 replaced by createColumnFieldMatrix(FieldElement[])
      Creates a column BigMatrix using the data from the input array.
      Parameters:
      columnData - the input column data
      Returns:
      a columnData x 1 BigMatrix
      Throws:
      IllegalArgumentException - if columnData is empty
      NullPointerException - if columnDatais null

    • createColumnBigMatrix

      @Deprecated public static BigMatrix createColumnBigMatrix(String[] columnData)
      Deprecated.
      since 2.0 replaced by createColumnFieldMatrix(FieldElement[])
      Creates a column BigMatrix using the data from the input array.
      Parameters:
      columnData - the input column data
      Returns:
      a columnData x 1 BigMatrix
      Throws:
      IllegalArgumentException - if columnData is empty
      NullPointerException - if columnDatais null

    • checkRowIndex

      public static void checkRowIndex(AnyMatrix m, int row)
      Check if a row index is valid.
      Parameters:
      m - matrix containing the submatrix
      row - row index to check
      Throws:
      MatrixIndexException - if index is not valid

    • checkColumnIndex

      public static void checkColumnIndex(AnyMatrix m, int column) throws MatrixIndexException
      Check if a column index is valid.
      Parameters:
      m - matrix containing the submatrix
      column - column index to check
      Throws:
      MatrixIndexException - if index is not valid

    • 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 containing the submatrix
      startRow - Initial row index
      endRow - Final row index
      startColumn - Initial column index
      endColumn - Final column index
      Throws:
      MatrixIndexException - if the indices are not valid

    • checkSubMatrixIndex

      public static void checkSubMatrixIndex(AnyMatrix m, int[] selectedRows, int[] selectedColumns) throws MatrixIndexException
      Check if submatrix ranges indices are valid. Rows and columns are indicated counting from 0 to n-1.
      Parameters:
      m - matrix containing the submatrix
      selectedRows - Array of row indices.
      selectedColumns - Array of column indices.
      Throws:
      MatrixIndexException - if row or column selections are not valid

    • checkAdditionCompatible

      public static void checkAdditionCompatible(AnyMatrix left, AnyMatrix right) throws IllegalArgumentException
      Check if matrices are addition compatible
      Parameters:
      left - left hand side matrix
      right - right hand side matrix
      Throws:
      IllegalArgumentException - if matrices are not addition compatible

    • checkSubtractionCompatible

      public static void checkSubtractionCompatible(AnyMatrix left, AnyMatrix right) throws IllegalArgumentException
      Check if matrices are subtraction compatible
      Parameters:
      left - left hand side matrix
      right - right hand side matrix
      Throws:
      IllegalArgumentException - if matrices are not subtraction compatible

    • checkMultiplicationCompatible

      public static void checkMultiplicationCompatible(AnyMatrix left, AnyMatrix right) throws IllegalArgumentException
      Check if matrices are multiplication compatible
      Parameters:
      left - left hand side matrix
      right - right hand side matrix
      Throws:
      IllegalArgumentException - 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:
      converted matrix

    • bigFractionMatrixToRealMatrix

      public static Array2DRowRealMatrix bigFractionMatrixToRealMatrix(FieldMatrix<BigFraction> m)
      Convert a FieldMatrix/BigFraction matrix to a RealMatrix.
      Parameters:
      m - matrix to convert
      Returns:
      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

      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:

    • 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

      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: