Class MatrixUtils


  • public class MatrixUtils
    extends java.lang.Object
    A collection of static methods that operate on or return matrices.
    • 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[][])
      • 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:
        java.lang.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:
        java.lang.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
      • 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.
      • 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.
      • serializeRealVector

        public static void serializeRealVector​(RealVector vector,
                                               java.io.ObjectOutputStream oos)
                                        throws java.io.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:
        java.io.IOException - if object cannot be written to stream
        See Also:
        deserializeRealVector(Object, String, ObjectInputStream)
      • deserializeRealVector

        public static void deserializeRealVector​(java.lang.Object instance,
                                                 java.lang.String fieldName,
                                                 java.io.ObjectInputStream ois)
                                          throws java.lang.ClassNotFoundException,
                                                 java.io.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:
        java.lang.ClassNotFoundException - if a class in the stream cannot be found
        java.io.IOException - if object cannot be read from the stream
        See Also:
        serializeRealVector(RealVector, ObjectOutputStream)
      • serializeRealMatrix

        public static void serializeRealMatrix​(RealMatrix matrix,
                                               java.io.ObjectOutputStream oos)
                                        throws java.io.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:
        java.io.IOException - if object cannot be written to stream
        See Also:
        deserializeRealMatrix(Object, String, ObjectInputStream)
      • deserializeRealMatrix

        public static void deserializeRealMatrix​(java.lang.Object instance,
                                                 java.lang.String fieldName,
                                                 java.io.ObjectInputStream ois)
                                          throws java.lang.ClassNotFoundException,
                                                 java.io.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:
        java.lang.ClassNotFoundException - if a class in the stream cannot be found
        java.io.IOException - if object cannot be read from the stream
        See Also:
        serializeRealMatrix(RealMatrix, ObjectOutputStream)
      • 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.