Package org.hipparchus.linear

Class MatrixUtils

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

  • Field Details

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

    • createRealMatrix

      public static RealMatrix createRealMatrix(double[][] data) throws MathIllegalArgumentException, NullArgumentException
      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:
      MathIllegalArgumentException - if data is not rectangular (not all rows have the same length).
      MathIllegalArgumentException - if a row or column is empty.
      NullArgumentException - if either data or data[0] is null.
      MathIllegalArgumentException - if data is not rectangular.
      See Also:

    • createFieldMatrix

      public static <T extends FieldElement<T>> FieldMatrix<T> createFieldMatrix(T[][] data) throws MathIllegalArgumentException, 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:
      MathIllegalArgumentException - if data is not rectangular (not all rows have the same length).
      MathIllegalArgumentException - if a row or column is empty.
      NullArgumentException - if either data or data[0] is null.
      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

    • 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

    • 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

    • 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

    • createRealVector

      public static RealVector createRealVector(double[] data) throws MathIllegalArgumentException, NullArgumentException
      Creates a RealVector using the data from the input array.
      Parameters:
      data - the input data
      Returns:
      a data.length RealVector
      Throws:
      MathIllegalArgumentException - if data is empty.
      NullArgumentException - if data is null.

    • createRealVector

      public static RealVector createRealVector(int dimension)
      Creates a RealVector with specified dimensions.
      Parameters:
      dimension - dimension of the vector
      Returns:
      a new vector
      Since:
      1.3

    • createFieldVector

      public static <T extends FieldElement<T>> FieldVector<T> createFieldVector(T[] data) throws MathIllegalArgumentException, NullArgumentException
      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:
      MathIllegalArgumentException - if data is empty.
      NullArgumentException - if data is null.
      MathIllegalArgumentException - if data has 0 elements

    • createFieldVector

      public static <T extends FieldElement<T>> FieldVector<T> createFieldVector(Field<T> field, int dimension)
      Creates a FieldVector with specified dimensions.
      Type Parameters:
      T - the type of the field elements
      Parameters:
      field - field to which array elements belong
      dimension - dimension of the vector
      Returns:
      a new vector
      Since:
      1.3

    • createRowRealMatrix

      public static RealMatrix createRowRealMatrix(double[] rowData) throws MathIllegalArgumentException, 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:
      MathIllegalArgumentException - if rowData is empty.
      NullArgumentException - if rowData is null.

    • createRowFieldMatrix

      public static <T extends FieldElement<T>> FieldMatrix<T> createRowFieldMatrix(T[] rowData) throws MathIllegalArgumentException, 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:
      MathIllegalArgumentException - if rowData is empty.
      NullArgumentException - if rowData is null.

    • createColumnRealMatrix

      public static RealMatrix createColumnRealMatrix(double[] columnData) throws MathIllegalArgumentException, 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:
      MathIllegalArgumentException - if columnData is empty.
      NullArgumentException - if columnData is null.

    • createColumnFieldMatrix

      public static <T extends FieldElement<T>> FieldMatrix<T> createColumnFieldMatrix(T[] columnData) throws MathIllegalArgumentException, 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:
      MathIllegalArgumentException - 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:
      MathIllegalArgumentException - if the matrix is not square.
      MathIllegalArgumentException - if the matrix is not symmetric.

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

    • checkMatrixIndex

      public static void checkMatrixIndex(AnyMatrix m, int row, int column) throws MathIllegalArgumentException
      Check if matrix indices are valid.
      Parameters:
      m - Matrix.
      row - Row index to check.
      column - Column index to check.
      Throws:
      MathIllegalArgumentException - if row or column is not a valid index.

    • checkRowIndex

      public static void checkRowIndex(AnyMatrix m, int row) throws MathIllegalArgumentException
      Check if a row index is valid.
      Parameters:
      m - Matrix.
      row - Row index to check.
      Throws:
      MathIllegalArgumentException - if row is not a valid index.

    • checkColumnIndex

      public static void checkColumnIndex(AnyMatrix m, int column) throws MathIllegalArgumentException
      Check if a column index is valid.
      Parameters:
      m - Matrix.
      column - Column index to check.
      Throws:
      MathIllegalArgumentException - if column is not a valid index.

    • checkSubMatrixIndex

      public static void checkSubMatrixIndex(AnyMatrix m, int startRow, int endRow, int startColumn, int endColumn) throws MathIllegalArgumentException
      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:
      MathIllegalArgumentException - if the indices are invalid.
      MathIllegalArgumentException - if endRow < startRow or endColumn < startColumn.

    • checkSubMatrixIndex

      public static void checkSubMatrixIndex(AnyMatrix m, int[] selectedRows, int[] selectedColumns) throws MathIllegalArgumentException, NullArgumentException
      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.
      MathIllegalArgumentException - if the row or column selections are empty (zero length).
      MathIllegalArgumentException - if row or column selections are not valid.

    • checkAdditionCompatible

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

    • checkSubtractionCompatible

      public static void checkSubtractionCompatible(AnyMatrix left, AnyMatrix right) throws MathIllegalArgumentException
      Check if matrices are subtraction compatible
      Parameters:
      left - Left hand side matrix.
      right - Right hand side matrix.
      Throws:
      MathIllegalArgumentException - if the matrices are not addition compatible.

    • checkMultiplicationCompatible

      public static void checkMultiplicationCompatible(AnyMatrix left, AnyMatrix right) throws MathIllegalArgumentException
      Check if matrices are multiplication compatible
      Parameters:
      left - Left hand side matrix.
      right - Right hand side matrix.
      Throws:
      MathIllegalArgumentException - if matrices are not multiplication compatible.

    • checkSameColumnDimension

      public static void checkSameColumnDimension(AnyMatrix left, AnyMatrix right) throws MathIllegalArgumentException
      Check if matrices have the same number of columns.
      Parameters:
      left - Left hand side matrix.
      right - Right hand side matrix.
      Throws:
      MathIllegalArgumentException - if matrices don't have the same number of columns.
      Since:
      1.3

    • checkSameRowDimension

      public static void checkSameRowDimension(AnyMatrix left, AnyMatrix right) throws MathIllegalArgumentException
      Check if matrices have the same number of rows.
      Parameters:
      left - Left hand side matrix.
      right - Right hand side matrix.
      Throws:
      MathIllegalArgumentException - if matrices don't have the same number of rows.
      Since:
      1.3

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

    • solveLowerTriangularSystem

      public static void solveLowerTriangularSystem(RealMatrix rm, RealVector b) throws MathIllegalArgumentException, MathRuntimeException
      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:
      MathIllegalArgumentException - if the matrix and vector are not conformable
      MathIllegalArgumentException - if the matrix rm is not square
      MathRuntimeException - 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 MathIllegalArgumentException, MathRuntimeException
      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:
      MathIllegalArgumentException - if the matrix and vector are not conformable
      MathIllegalArgumentException - if the matrix rm is not square
      MathRuntimeException - 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:
      MathIllegalArgumentException - if m is not square.

    • inverse

      public static RealMatrix inverse(RealMatrix matrix) throws MathIllegalArgumentException, NullArgumentException
      Computes the inverse of the given matrix.

      By default, the inverse of the matrix is computed using the QR-decomposition, unless a more efficient method can be determined for the input matrix.

      Note: this method will use a singularity threshold of 0, use inverse(RealMatrix, double) if a different threshold is needed.

      Parameters:
      matrix - Matrix whose inverse shall be computed
      Returns:
      the inverse of matrix
      Throws:
      NullArgumentException - if matrix is null
      MathIllegalArgumentException - if m is singular
      MathIllegalArgumentException - if matrix is not square

    • inverse

      public static RealMatrix inverse(RealMatrix matrix, double threshold) throws MathIllegalArgumentException, NullArgumentException
      Computes the inverse of the given matrix.

      By default, the inverse of the matrix is computed using the QR-decomposition, unless a more efficient method can be determined for the input matrix.

      Parameters:
      matrix - Matrix whose inverse shall be computed
      threshold - Singularity threshold
      Returns:
      the inverse of m
      Throws:
      NullArgumentException - if matrix is null
      MathIllegalArgumentException - if matrix is singular
      MathIllegalArgumentException - if matrix is not square

    • matrixExponential

      public static RealMatrix matrixExponential(RealMatrix rm)
      Computes the matrix exponential of the given matrix. The algorithm implementation follows the Pade approximant method of

      Higham, Nicholas J. “The Scaling and Squaring Method for the Matrix Exponential Revisited.” SIAM Journal on Matrix Analysis and Applications 26, no. 4 (January 2005): 1179–93.

      Parameters:
      rm - RealMatrix whose inverse shall be computed
      Returns:
      The inverse of rm
      Throws:
      MathIllegalArgumentException - if matrix is not square

    • orthonormalize

      public static List<RealVector> orthonormalize(List<RealVector> independent, double threshold, DependentVectorsHandler handler)
      Orthonormalize a list of vectors.

      Orthonormalization is performed by using the Modified Gram-Schmidt process.

      Parameters:
      independent - list of independent vectors
      threshold - projected vectors with a norm less than or equal to this threshold are considered to have zero norm, hence the vectors they come from are not independent from previous vectors
      handler - handler for dependent vectors
      Returns:
      orthonormal basis having the same span as independent
      Since:
      2.1

    • orthonormalize

      public static <T extends CalculusFieldElement<T>> List<FieldVector<T>> orthonormalize(Field<T> field, List<FieldVector<T>> independent, T threshold, DependentVectorsHandler handler)
      Orthonormalize a list of vectors.

      Orthonormalization is performed by using the Modified Gram-Schmidt process.

      Type Parameters:
      T - type of the field elements
      Parameters:
      independent - list of independent vectors
      threshold - projected vectors with a norm less than or equal to this threshold are considered to have zero norm, hence the vectors they come from are not independent from previous vectors
      field - type of the files elements
      handler - handler for dependent vectors
      Returns:
      orthonormal basis having the same span as independent
      Since:
      2.1