Package com.mvohm.quadmatrix

Class Matrix

java.lang.Object
com.mvohm.quadmatrix.Matrix
Direct Known Subclasses:
BigDecimalMatrix, DoubleMatrix, QuadrupleMatrix
public abstract class Matrix extends Object
A generic abstract class which defines the set of operations that all its subclasses must implement.
Instances of subclasses are capable of:
  • solving systems of linear equations of the forms A * X = B and A * x = b, including versions with enhanced accuracy that use an iterative refinement of the solution (see solve(Number[]), solveAccurately(Number[]), solve(Matrix) and alike);
  • inversion (including a version with enhanced accuracy) and transposition of the matrix;
  • multiplying this matrix by another matrix, by a vector, and by a scalar;
  • addition and subtraction of a matrix;
  • computation of the determinant.
Instances of the matrix are immutable; all operations whose results are matrices create and return new instances representing the resulting matrices.
Author:
M.Vokhmentev

  • Method Summary

    Modifier and Type
    Method
    Description
    abstract Matrix
    add(double[][] matrixB)
    Adds the given matrixB passed in as a two-dimentional array of doubles to this matrix and returns the sum.
    abstract Matrix
    add(Matrix matrixB)
    Adds the given matrixB to this matrix and returns the sum.
    abstract Matrix
    add(Number[][] matrixB)
    Adds the given matrixB passed in as a two-dimentional array of Number to this matrix and returns the sum.
    abstract double
    cond()
    Computes the condition number of the matrix, ║A║•║A-1║, and returns its value as a double value.
    abstract Number
    determinant()
    Computes the determinant of the matrix and returns its value as a Number value.
    abstract BigDecimal
    determinantAsBigDecimal()
    Computes the determinant of the matrix and returns its value as a BigDecimal value.
    abstract double
    determinantAsDouble()
    Computes the determinant of the matrix and returns its value as a double value.
    abstract Quadruple
    determinantAsQuadruple()
    Computes the determinant of the matrix and returns its value as a Quadruple value.
    abstract boolean
    equals(Object anotherOne)
    Indicates whether the other Matrix is equal to this one.
    abstract BigDecimal[][]
    getBigDecimalData()
    Returns a two-dimentional array of BigDecimal instances containing the values of the corresponding matrix elements.
    abstract BigDecimal[][]
    getBigDecimalMatrixSolution()
    Returns the last of the previously found matrix solutions, X, to a matrix equation of form AX = B, as a two-dimentional array of BigDecimals.
    abstract BigDecimal[]
    getBigDecimalSolution()
    Returns the last of the previously found vector solutions, x, to a system of linear equations of form Ax = b, as an array of BigDecimals.
    abstract Number[][]
    getData()
    Returns a two-dimentional array of Number containing the values of the corresponding matrix elements.
    abstract double[][]
    getDoubleData()
    Returns a two-dimentional array of primitive double values containing the values of the corresponding matrix elements, perhaps rounded.
    abstract double[][]
    getDoubleMatrixSolution()
    Returns the last of the previously found matrix solutions, X, to a matrix equation of form AX = B, as a two-dimentional array of primitive doubles.
    abstract double[]
    getDoubleSolution()
    Returns a copy of the last previously found vector solutions, x, to a system of linear equations of form Ax = b, as an array of doubles.
    abstract String
    getErrorCode()
    Returns a string designation of the error code if an error has occurred during the solving or inversion of the matrix.
    abstract Matrix
    getMatrixSolution()
    Returns the last of the previously found matrix solutions, X, to a matrix equation of form AX = B, as a Matrix.
    abstract Number[][]
    getNumberMatrixSolution()
    Returns the last of the previously found matrix solutions, X, to a matrix equation of form AX = B, as a two-dimentional array of Number.
    abstract Quadruple[][]
    getQuadrupleData()
    Returns a two-dimentional array of Quadruple instances containing the values of the corresponding matrix elements, perhaps rounded.
    abstract Quadruple[][]
    getQuadrupleMatrixSolution()
    Returns the last of the previously found matrix solutions, X, to a matrix equation of form AX = B, as a two-dimentional array of Quadruples.
    abstract Quadruple[]
    getQuadrupleSolution()
    Returns the last of the previously found vector solutions, x, to a system of linear equations of form Ax = b, as an array of Quadruples.
    abstract boolean
    getScaling()
    Returns the value of an internal flag that defines whether row scaling will be applied while solving a system by this instance of Matrix.
    int
    getSize()
    Returns the size of the matrix, m for a matrix m x m
    abstract Number[]
    getSolution()
    Returns a copy of the last previously found vector solutions, x, to a system of linear equations of form Ax = b, as an array of Numbers.
    abstract int
    hashCode()
    Returns a hash code value for the Matrix.
    abstract Matrix
    inverse()
    Creates and returns a new Matrix instance containing the inversion of this instance.
    abstract Matrix
    inverseAccurately()
    Creates and returns a new Matrix instance containing the inversion of this instance.
    abstract Matrix
    multiply(double scalar)
    Multiplies this instance of Matrix by a scalar factor scalar passed in as a double parameter, and creates and returns a new matrix containing the product.
    abstract Number[]
    multiply(double[] vector)
    Multiplies this instance of Matrix by a vector passed in as an array of doubles, and returns an array of Number values containing the product.
    abstract Matrix
    multiply(double[][] factor)
    Multiplies this instance of Matrix by the factor passed in as a two-dimentional double array, and creates and returns a new matrix containing the product.
    abstract Matrix
    multiply(Matrix factor)
    Multiplies this instance of Matrix by the matrix passed in as the factor argument, creates and returns a new matrix containing the product.
    abstract Matrix
    multiply(Number scalar)
    Multiplies this instance of Matrix by a scalar factor scalar passed in as a Number parameter, and creates and returns a new matrix containing the product.
    abstract Number[]
    multiply(Number[] vector)
    Multiplies this instance of Matrix by a vector passed in as an array of Number values and returns an array of Number values containing the product.
    abstract Matrix
    multiply(Number[][] factor)
    Multiplies this instance of Matrix by the factor passed in as a two-dimentional array of Numbers, and creates and returns a new matrix containing the product.
    abstract Number
    norm()
    Computes the row-based norm of the matrix, ║A║∞, and returns its value as a Number value.
    abstract BigDecimal
    normAsBigDecimal()
    Computes the row-based norm of the matrix, ║A║∞, and returns its value as a BigDecimal value.
    abstract double
    normAsDouble()
    Computes the row-based norm of the matrix, ║A║∞, and returns its value as a double value.
    abstract Quadruple
    normAsQuadruple()
    Computes the row-based norm of the matrix, ║A║∞, and returns its value as a Quadruple value.
    abstract Number[]
    solve(double[] vector)
    Solves a system of linear equations of form Ax = b and returns the found solution.
    abstract Matrix
    solve(double[][] matrixB)
    Solves a matrix equation of form AX = B and returns the found solution.
    abstract Matrix
    solve(Matrix matrixB)
    Solves a matrix equation of form AX = B and returns the found solution.
    abstract Number[]
    solve(Number[] vector)
    Solves a system of linear equations of form Ax = b and returns the found solution.
    abstract Matrix
    solve(Number[][] matrixB)
    Solves a matrix equation of form AX = B and returns the found solution.
    abstract Number[]
    solveAccurately(double[] vector)
    Solves a system of linear equations of form Ax = b with increased accuracy and returns the found solution.
    abstract Matrix
    solveAccurately(double[][] matrixB)
    Solves a matrix equation of form AX = B and returns the found solution.
    abstract Matrix
    solveAccurately(Matrix matrixB)
    Solves a matrix equation of form AX = B and returns the found solution.
    abstract Number[]
    solveAccurately(Number[] vector)
    Solves a system of linear equations of form Ax = b with increased accuracy and returns the found solution.
    abstract Matrix
    solveAccurately(Number[][] matrixB)
    Solves a matrix equation of form AX = B and returns the found solution.
    abstract Number[]
    solveSPD(double[] vector)
    Solves a system of linear equations of form Ax = b for a symmetric positively-defined matrix of coefficients and returns the found solution.
    abstract Number[]
    solveSPD(Number[] vector)
    Solves a system of linear equations of form Ax = b for a symmetric positively-defined matrix of coefficients and returns the found solution.
    abstract Number[]
    solveSPDAccurately(double[] vector)
    Solves a system of linear equations of form Ax = b for a symmetric positively-defined matrix of coefficients, using an iterative refinement algorithm to achieve higher solution accuracy, and returns the found solution.
    abstract Number[]
    solveSPDAccurately(Number[] vector)
    Solves a system of linear equations of form Ax = b for a symmetric positively-defined matrix of coefficients, using an iterative refinement algorithm to achieve higher solution accuracy, and returns the found solution.
    abstract Matrix
    subtract(double[][] matrixB)
    Subtracts the given matrixB passed in as a two-dimentional array of doubles from this matrix and returns the difference.
    abstract Matrix
    subtract(Matrix matrixB)
    Subtracts the given matrixB from this matrix and returns the difference.
    abstract Matrix
    subtract(Number[][] matrixB)
    Subtracts the given matrixB passed in as a two-dimentional array of Number from this matrix and returns the difference.
    abstract Matrix
    transpose()
    Creates and returns a new Matrix instance containing the transposition of this instance.
    abstract Matrix
    unity()
    Creates and returns a new Matrix instance containing a unity matrix of the same size as the source matrix.

    Methods inherited from class java.lang.Object

    getClass, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • getSize

      public int getSize()
      Returns the size of the matrix, m for a matrix m x m
      Returns:
      the size of the matrix

    • getScaling

      public abstract boolean getScaling()
      Returns the value of an internal flag that defines whether row scaling will be applied while solving a system by this instance of Matrix.
      Scaling of the rows of the matrix may be used while solving systems of linear equations. When an internal flag controlling the scaling is set to true, the rows of the matrix along with the corresponding elements of the vector b or the matrix B are scaled so that the norms of the rows are all be 1.0. In most cases this improves the accuracy of the solution, especially for matrices including both very large and very small elements. The default value of the flag signifying the necessity of the scaling for a certain subclass may be set via a static method setScaling() of the subclass, and the necessity of the scaling for a newly-created instance of Matrix may be controlled via the corresponding parameter of a constructor.
      Returns:
      the value of the flag that defines whether the scaling will be applied while solving a system by this instance of Matrix

    • getData

      public abstract Number[][] getData()
      Returns a two-dimentional array of Number containing the values of the corresponding matrix elements.
      The exact type of the array elements depends on the particular subclass of this instance (it is Double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc).
      The returned array is a copy of the corresponding internal array and can be safely modified. There is no loss of precision when copying, so the returned values are exactly equal to the values of the corresponding elements of the internal storage.
      Returns:
      a two-dimentional array of Number containing the values of the corresponding matrix elements.

    • getDoubleData

      public abstract double[][] getDoubleData()
      Returns a two-dimentional array of primitive double values containing the values of the corresponding matrix elements, perhaps rounded.
      If the type of the internal data of the particular class enables for higher precision than that provided by double, the values get rounded to the nearest possible double value.
      If the value of an internal data element exceeds the range of double values, it gets converted to Double.POSITIVE_INFINITY or Double.NEGATIVE_INFINITY, depending on its sign.
      Returns:
      a two-dimentional array of primitive double values containing the values of the corresponding matrix elements, perhaps rounded.

    • getQuadrupleData

      public abstract Quadruple[][] getQuadrupleData()
      Returns a two-dimentional array of Quadruple instances containing the values of the corresponding matrix elements, perhaps rounded.
      If the type of the internal data of the particular class enables for higher precision than that provided by Quadruple, the values get rounded to the nearest possible Quadruple value.
      If the value of an internal data element exceeds the range of Quadruple values, it gets converted to Quadruple.POSITIVE_INFINITY or Quadruple.NEGATIVE_INFINITY, depending on its sign.
      Returns:
      a two-dimentional array of Quadruple values containing the values of the corresponding matrix elements, perhaps rounded.

    • getBigDecimalData

      public abstract BigDecimal[][] getBigDecimalData()
      Returns a two-dimentional array of BigDecimal instances containing the values of the corresponding matrix elements.
      If the type of the internal data of the particular class is double then the corresponding BigDecimal values are obtained using BigDecimal.valueOf(double) method. If the type of the internal data of the particular class is Quadruple then the corresponding BigDecimal values are obtained using Quadruple.bigDecimalValue() method. If an internal data element is not convertible to BigDecimal (i.e. it is NaN or Infinity), throws NumberFormatException.
      Returns:
      a two-dimentional array of BigDecimal values containing the values of the corresponding matrix elements translated to BigDecimal instances.

    • equals

      public abstract boolean equals(Object anotherOne)
      Indicates whether the other Matrix is equal to this one.
      Matrices are considered to be equal if they belong to the same subtype, and their internal arrays containing the elements of the matrices are equal, and their needToScale flags are equal.
      Under those condition, the matrices yield equal results for all operations performed on them.
      Overrides:
      equals in class Object
      Returns:
      true, if the matrices are equal.

    • hashCode

      public abstract int hashCode()
      Returns a hash code value for the Matrix.
      It is guaranteed, that for two matrices returning different hashcodes their equals(Object) methods return false, and two matrices considered to be equal return equal hashcodes. For two different matrices, the probability of the equality of their hashcodes is reasonably low.
      Overrides:
      hashCode in class Object
      Returns:
      a hash code value for this object.
      See Also:

    • solve

      public abstract Number[] solve(double[] vector)
      Solves a system of linear equations of form Ax = b and returns the found solution.
      Solves the system Ax = b, formed by the inner matrix data A and the vector b passed in as the vector argument, using LU decomposition.
      The exact type of the elements of the returned array depends on the particular subclass of this instance (it is Double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc).
      In case of an inconsistent or underdefined matrix throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode().
      If the length of the vector does not match the size of the matrix, or the argument contains non-numeric values (NaN or Infinity), throws IllegalArgumentException with a relevant message.
      Parameters:
      vector - the column vector b of the equation to be solved, Ax = b, as an array of doubles
      Returns:
      the found solution x to the equation Ax = b as an array of Number instances whose particular type depends on the particular Matrix subtype.
      Throws:
      IllegalArgumentException - if the length of the vector does not match the size of the matrix,, or the system has no solution or has infinitely many solutions, or the argument contains non-numeric values (NaN or Infinity).
      NullPointerException - if the argument is null
      See Also:

    • solve

      public abstract Number[] solve(Number[] vector)
      Solves a system of linear equations of form Ax = b and returns the found solution.
      Solves the system Ax = b, formed by the inner matrix data A and the vector b passed in as the vector argument, using LU decomposition. Before solving, the given vector gets translated to an array of values of the type that is used to store internal matrix data (double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc).
      The exact type of the elements of the returned array depends on the particular subclass of this instance (it is Double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc).
      In case of an inconsistent or underdefined matrix throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode().
      If the length of the vector does not match the size of the matrix, or vector contains non-numeric values (NaN or Infinity) or null, throws IllegalArgumentException with a relevant message.
      Parameters:
      vector - the column vector b of the equation to be solved, Ax = b, as an array of Numbers
      Returns:
      the found solution x to the equation Ax = b as an array of Number instances, whose particular type depends on the particular Matrix subtype.
      Throws:
      IllegalArgumentException - if the length of the vector does not match the size of the matrix, or the system has no solution or has infinitely many solutions, or the argument contains invalid values (NaN, Infinity, or null).
      NullPointerException - if the argument is null
      See Also:

    • solveSPD

      public abstract Number[] solveSPD(double[] vector)
      Solves a system of linear equations of form Ax = b for a symmetric positively-defined matrix of coefficients and returns the found solution.
      Solves the system Ax = b, formed by the inner matrix data A and the vector b passed in as the vector argument, using Cholesky decomposition. The exact type of the elements of the returned array depends on the particular subclass of this instance (it is Double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc).
      In case of an asymmetric or non-positively-defined matrix throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode().
      If the length of the vector does not match the size of the matrix, or the argument contains non-numeric values (NaN or Infinity), throws IllegalArgumentException with a relevant message.
      Parameters:
      vector - the column vector b of the equation to be solved, Ax = b, as an array of Numbers
      Returns:
      the found solution x to the equation Ax = b as an array of Number instances, whose particular type depends on the particular Matrix subtype.
      Throws:
      IllegalArgumentException - if the length of the vector does not match the size of the matrix, or the matrix is asymmetric or not positively-defined, or the argument contains non-numeric values (NaN or Infinity).
      NullPointerException - if the argument is null
      See Also:

    • solveSPD

      public abstract Number[] solveSPD(Number[] vector)
      Solves a system of linear equations of form Ax = b for a symmetric positively-defined matrix of coefficients and returns the found solution.
      Solves the system Ax = b, formed by the inner matrix data A and the vector b passed in as the vector argument, using Cholesky decomposition. Before solving, the given vector gets translated to an array of values of the type that is used to store internal matrix data (double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc). The exact type of the elements of the returned array depends on the particular subclass of this instance (it is Double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc).
      In case of an asymmetric or non-positively-defined matrix throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode().
      If the length of the vector does not match the size of the matrix, or vector contains non-numeric values (NaN or Infinity) or null, throws IllegalArgumentException with a relevant message.
      Parameters:
      vector - the column vector b of the equation to be solved, Ax = b, as an array of Numbers
      Returns:
      the found solution x to the equation Ax = b as an array of Number instances, whose particular type depends on the particular Matrix subtype.
      Throws:
      IllegalArgumentException - if the length of the vector does not match the size of the matrix, or the matrix is asymmetric or not positively-defined, or the argument contains invalid values (NaN, Infinity, or null)
      NullPointerException - if the argument is null
      See Also:

    • solveAccurately

      public abstract Number[] solveAccurately(double[] vector)
      Solves a system of linear equations of form Ax = b with increased accuracy and returns the found solution.
      Solves the system Ax = b, formed by the inner matrix data A and the vector b passed in as the vector argument, using LU decomposition. Uses an iterative refinement to find a more accurate solution. The exact type of the elements of the returned array depends on the particular subclass of this instance (it is Double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc).
      In case of an inconsistent or underdefined matrix throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode().
      If the length of the vector does not match the size of the matrix, or vector contains non-numeric values (NaN or Infinity), throws IllegalArgumentException with a relevant message.
      Parameters:
      vector - the column vector b of the equation to be solved, Ax = b, as an array of doubles
      Returns:
      the found solution x to the equation Ax = b as an array of Number instances, whose particular type depends on the particular Matrix subtype.
      Throws:
      IllegalArgumentException - if the length of the vector does not match the size of the matrix, or the system has no solution or has infinitely many solutions, or the argument contains non-numeric values (NaN or Infinity).
      NullPointerException - if the argument is null
      See Also:

    • solveAccurately

      public abstract Number[] solveAccurately(Number[] vector)
      Solves a system of linear equations of form Ax = b with increased accuracy and returns the found solution.
      Solves the system Ax = b, formed by the inner matrix data A and the vector b passed in as the vector argument, using LU decomposition. Before solving, the given vector gets translated to an array of values of the type that is used to store internal matrix data (double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc).
      Uses an iterative refinement to find a more accurate solution. The exact type of the elements of the returned array depends on the particular subclass of this instance (it is Double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc).
      In case of an inconsistent or underdefined matrix throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode().
      If the length of the vector does not match the size of the matrix, or vector contains non-numeric values (NaN or Infinity) or null, throws IllegalArgumentException with a relevant message.
      Parameters:
      vector - the column vector b of the equation to be solved, Ax = b, as an array of Numbers
      Returns:
      the found solution x to the equation Ax = b as an array of Number instances, whose particular type depends on the particular Matrix subtype.
      Throws:
      IllegalArgumentException - if the length of the vector does not match the size of the matrix, or the system has no solution or has infinitely many solutions, or the argument contains invalid values (NaN, Infinity, or null)
      NullPointerException - if the argument is null
      See Also:

    • solveSPDAccurately

      public abstract Number[] solveSPDAccurately(double[] vector)
      Solves a system of linear equations of form Ax = b for a symmetric positively-defined matrix of coefficients, using an iterative refinement algorithm to achieve higher solution accuracy, and returns the found solution.
      Solves the system Ax = b, formed by the inner matrix data A and the vector b passed in as the vector argument, using Cholesky decomposition. Uses an iterative refinement to find a more accurate solution. The exact type of the elements of the returned array depends on the particular subclass of this instance (it is Double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc).
      In case of an asymmetric or non-SPD matrix throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode().
      If the length of the vector does not match the size of the matrix, or vector contains non-numeric values (NaN or Infinity), throws IllegalArgumentException with a relevant message.
      Parameters:
      vector - the column vector b of the equation to be solved, Ax = b, as an array of doubles
      Returns:
      the found solution x to the equation Ax = b as an array of Number instances, whose particular type depends on the particular Matrix subtype.
      Throws:
      IllegalArgumentException - if the length of the vector does not match the size of the matrix, or the matrix is asymmetric or not positively-defined, or the argument contains non-numeric values (NaN or Infinity).
      NullPointerException - if the argument is null
      See Also:

    • solveSPDAccurately

      public abstract Number[] solveSPDAccurately(Number[] vector)
      Solves a system of linear equations of form Ax = b for a symmetric positively-defined matrix of coefficients, using an iterative refinement algorithm to achieve higher solution accuracy, and returns the found solution.
      Solves the system Ax = b, formed by the inner matrix data A and the vector b passed in as the vector argument, using Cholesky decomposition. Uses an iterative refinement to find a more accurate solution. The exact type of the elements of the returned array depends on the particular subclass of this instance (it is Double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc).
      In case of an asymmetric or non-SPD matrix throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode(). If the length of the vector does not match the size of the matrix, or vector contains non-numeric values (NaN or Infinity) or null throws IllegalArgumentException with a relevant message.
      Parameters:
      vector - the column vector b of the equation to be solved, Ax = b, as an array of doubles
      Returns:
      the found solution x to the equation Ax = b as an array of Number instances, whose particular type depends on the particular Matrix subtype.
      Throws:
      IllegalArgumentException - if the length of the vector does not match the size of the matrix, or the matrix is asymmetric or not positively-defined, or the argument contains invalid values (NaN, Infinity, or null)
      NullPointerException - if the argument is null
      See Also:

    • getSolution

      public abstract Number[] getSolution()
      Returns a copy of the last previously found vector solutions, x, to a system of linear equations of form Ax = b, as an array of Numbers.
      The exact type of the elements of the returned array depends on the particular subclass of this instance (it is Double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc).
      If no system was solved with this instance of the Matrix, returns null.
      Returns:
      the last of the previously found vector solutions, x, to a system of linear equations of form Ax = b, as an array of Numbers, or null, if no system was solved with the matrix.

    • getDoubleSolution

      public abstract double[] getDoubleSolution()
      Returns a copy of the last previously found vector solutions, x, to a system of linear equations of form Ax = b, as an array of doubles.
      If the particular subtype of the instance stores internal data with higher precision than that provided by double, the values of the elements of the returned vector get rounded to the nearest double values.
      If no system was solved with this instance of the Matrix, returns null.
      Returns:
      the last of the previously found vector solutions, x, to a system of linear equations of form Ax = b, as an array of primitive doubles. or null, if no system was solved with the matrix.

    • getQuadrupleSolution

      public abstract Quadruple[] getQuadrupleSolution()
      Returns the last of the previously found vector solutions, x, to a system of linear equations of form Ax = b, as an array of Quadruples.
      If the particular subtype of the instance stores internal data with higher precision than that provided by Quadruple, the values of the elements of the returned vector get rounded to the nearest double values.
      If no system was solved with this instance of the Matrix, returns null.
      Returns:
      the last of the previously found vector solutions, x, to a system of linear equations of form Ax = b, as an array of Quadruples, or null, if no system was solved with the matrix.

    • getBigDecimalSolution

      public abstract BigDecimal[] getBigDecimalSolution()
      Returns the last of the previously found vector solutions, x, to a system of linear equations of form Ax = b, as an array of BigDecimals.
      If no system was solved with this instance of the Matrix, returns null.
      If the solution contains values that can't be translated to BigDeciaml (NaN or Infinity), throws NumberFormatException.
      Returns:
      the last of the previously found vector solutions, x, to a system of linear equations of form Ax = b, as an array of BigDecimals. or null, if no system was solved with the matrix.

    • getErrorCode

      public abstract String getErrorCode()
      Returns a string designation of the error code if an error has occurred during the solving or inversion of the matrix.
      This method can return the following values:
      • "OK" -- The last solution or inversion was successful;
      • "ASYMMETRIC" -- There was an attempt to solve or inverse the matrix using Cholesky decomposition, but the matrix is asymmetric;
      • "NON_SPD" -- There was an attempt to solve or inverse the matrix using Cholesky decomposition, but the matrix is not positively-defined;
      • "NON_INVERTIBLE" -- There was an attempt to solve or inverse the matrix using LU decomposition, but the matrix is inconsistent or underdetermined
      If no operations requiring decompositions were performed with this instance yet, returns OK.
      Returns:
      a string designation of the error code if an error has occurred during the solving or inversion of the matrix, or "OK" in case of success.
      See Also:
      • Matrix.ErrorCodes

    • solve

      public abstract Matrix solve(Matrix matrixB)
      Solves a matrix equation of form AX = B and returns the found solution.
      Solves a matrix equation of form AX = B formed by the inner matrix data A and the matrix B passed in as the Matrix matrixB argument, using LU decomposition.
      In case of an inconsistent or underdefined matrix throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode(). If the size of the matrixB does not match the size of this instance of the matrix, throws IllegalArgumentException with a relevant message.
      Parameters:
      matrixB - the matrix B of the equation to be solved, AX = B
      Returns:
      the found solution X to the equation AX = B as a new instance of Matrix of the same particular subtype as this instance.
      Throws:
      IllegalArgumentException - if the size of the matrixB does not match the size of this instance or the system has no solution or has infinitely many solutions.
      NullPointerException - if the argument is null
      See Also:

    • solve

      public abstract Matrix solve(double[][] matrixB)
      Solves a matrix equation of form AX = B and returns the found solution.
      Solves a matrix equation of form AX = B formed by the inner matrix data A and the matrix B passed in as the double[][] matrixB argument, using LU decomposition.
      In case of an inconsistent or underdefined matrix throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode().
      If the passed-in array is non-square, or its size does not match the size of this instance of the matrix, or the argument contains non-numeric values (NaN or Infinity), throws IllegalArgumentException with a relevant message.
      Parameters:
      matrixB - the matrix B of the equation to be solved, AX = B, as a two-dimentional array of primitive doubles
      Returns:
      the found solution X to the equation AX = B as a new instance of Matrix of the same particular subtype as this instance.
      Throws:
      IllegalArgumentException - if the passed-in array is non-square, or its size does not match the size of this instance, or the system has no solution or has infinitely many solutions, or the argument contains non-numeric values (NaN or Infinity).
      NullPointerException - if the argument is null
      See Also:

    • solve

      public abstract Matrix solve(Number[][] matrixB)
      Solves a matrix equation of form AX = B and returns the found solution.
      Solves a matrix equation of form AX = B formed by the inner matrix data A and the matrix B passed in as the Number[][] matrixB argument, using LU decomposition.
      Before solving, the given matrixB array gets translated to an array of values of the type that is used to store internal matrix data (double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc).
      In case of an inconsistent or underdefined matrix throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode().
      If the passed-in array is non-square, or its size does not match the size of this instance of the matrix, or matrixB contains non-numeric values (NaN or Infinity) or null, throws IllegalArgumentException with a relevant message.
      Parameters:
      matrixB - the matrix B of the equation to be solved, AX = B, as a two-dimentional array of Number
      Returns:
      the found solution X to the equation AX = B as a new instance of Matrix of the same particular subtype as this instance.
      Throws:
      IllegalArgumentException - if the passed-in array is non-square, or its size does not match the size of this instance, or the system has no solution or has infinitely many solutions, or the argument contains invalid values (NaN, Infinity, or null).
      NullPointerException - if the argument is null
      See Also:

    • solveAccurately

      public abstract Matrix solveAccurately(Matrix matrixB)
      Solves a matrix equation of form AX = B and returns the found solution.
      Solves a matrix equation of form AX = B formed by the inner matrix data A and the matrix B passed in as the matrixB argument, using LU decomposition.
      Uses an iterative refinement to find a more accurate solution.
      In case of an inconsistent or underdefined matrix throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode().
      If the size of the matrixB does not match the size of this instance of the matrix, throws IllegalArgumentException with a relevant message.
      Parameters:
      matrixB - the matrix B of the equation to be solved, AX = B
      Returns:
      the found solution X to the equation AX = B as a new instance of Matrix of the same particular subtype as this instance.
      Throws:
      IllegalArgumentException - if the size of the matrixB does not match the size of this instance or the system has no solution or has infinitely many solutions.
      NullPointerException - if the argument is null
      See Also:

    • solveAccurately

      public abstract Matrix solveAccurately(double[][] matrixB)
      Solves a matrix equation of form AX = B and returns the found solution.
      Solves a matrix equation of form AX = B formed by the inner matrix data A and the matrix B passed in as the double[][] matrixB argument, using LU decomposition.
      Uses an iterative refinement to find a more accurate solution. In case of an inconsistent or underdefined matrix throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode().
      If the passed-in array is non-square, or its size does not match the size of this instance of the matrix, or the argument contains non-numeric values (NaN or Infinity), throws IllegalArgumentException with a relevant message.
      Parameters:
      matrixB - the matrix B of the equation to be solved, AX = B, as a two-dimentional array of primitive doubles
      Returns:
      the found solution X to the equation AX = B as a new instance of Matrix of the same particular subtype as this instance.
      Throws:
      IllegalArgumentException - if the size of the matrixB does not match the size of this instance or the system has no solution or has infinitely many solutions, or the argument contains non-numeric values (NaN or Infinity).
      NullPointerException - if the argument is null
      See Also:

    • solveAccurately

      public abstract Matrix solveAccurately(Number[][] matrixB)
      Solves a matrix equation of form AX = B and returns the found solution.
      Solves a matrix equation of form AX = B formed by the inner matrix data A and the matrix B passed in as the Number[][] matrixB argument, using LU decomposition.
      Before solving, the given matrixB array gets translated to an array of values of the type that is used to store internal matrix data (double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc).
      Uses an iterative refinement to find a more accurate solution. In case of an inconsistent or underdefined matrix throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode().
      If the passed-in array is non-square, or its size does not match the size of this instance of the matrix, or matrixB contains non-numeric values (NaN or Infinity) or null, throws IllegalArgumentException with a relevant message.
      Parameters:
      matrixB - the matrix B of the equation to be solved, AX = B, as a two-dimentional array of Number
      Returns:
      the found solution X to the equation AX = B as a new instance of Matrix of the same particular subtype as this instance.
      Throws:
      IllegalArgumentException - if the size of the matrixB does not match the size of this instance or the system has no solution or has infinitely many solutions, or the argument contains invalid values (NaN, Infinity, or null).
      NullPointerException - if the argument is null
      See Also:

    • getMatrixSolution

      public abstract Matrix getMatrixSolution()
      Returns the last of the previously found matrix solutions, X, to a matrix equation of form AX = B, as a Matrix. If no matrix equation was solved with this instance of the Matrix, returns null.
      Returns:
      the last of the previously found matrix solution X, to a system of linear equations of form AX = B, as a Matrix, or null, if no matrix equation was solved with the matrix.

    • getNumberMatrixSolution

      public abstract Number[][] getNumberMatrixSolution()
      Returns the last of the previously found matrix solutions, X, to a matrix equation of form AX = B, as a two-dimentional array of Number.
      The particular type of the elements of the returned vector depends on the particular subtype of Matrix (it is Double for DoubleMatrix, Quadruple for QuadrupleMatrix, etc).
      If no matrix equation was solved with this instance of the Matrix, returns null.
      Returns:
      the last of the previously found matrix solution X, to a system of linear equations of form AX = B, as two-dimentional array of Number, or null, if no matrix equation was solved with the matrix.

    • getDoubleMatrixSolution

      public abstract double[][] getDoubleMatrixSolution()
      Returns the last of the previously found matrix solutions, X, to a matrix equation of form AX = B, as a two-dimentional array of primitive doubles.
      If no matrix equation was solved with this instance of the Matrix, returns null.
      Returns:
      the last of the previously found matrix solution X, to a system of linear equations of form AX = B, as two-dimentional array of doubles, or null, if no matrix equation was solved with the matrix.

    • getQuadrupleMatrixSolution

      public abstract Quadruple[][] getQuadrupleMatrixSolution()
      Returns the last of the previously found matrix solutions, X, to a matrix equation of form AX = B, as a two-dimentional array of Quadruples.
      If no matrix equation was solved with this instance of the Matrix, returns null.
      Returns:
      the last of the previously found matrix solution X, to a system of linear equations of form AX = B, as two-dimentional array of Quadruples, or null, if no matrix equation was solved with the matrix.

    • getBigDecimalMatrixSolution

      public abstract BigDecimal[][] getBigDecimalMatrixSolution()
      Returns the last of the previously found matrix solutions, X, to a matrix equation of form AX = B, as a two-dimentional array of BigDecimals.
      If no matrix equation was solved with this instance of the Matrix, returns null.
      Returns:
      the last of the previously found matrix solution X, to a system of linear equations of form AX = B, as two-dimentional array of BigDecimal, or null, if no matrix equation was solved with the matrix.

    • inverse

      public abstract Matrix inverse()
      Creates and returns a new Matrix instance containing the inversion of this instance.
      Computes the inversion of the matrix by solving the equation AX = E, creates and returns a new Matrix containing the found inversion. The exact subtype of the returned matrix is the same as that of this instance. If the matrix is not invertible (i.e. inconsistent or underdefined), throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode().
      Returns:
      a new Matrix containing the inversion of the given matrix.
      Throws:
      IllegalArgumentException - if the matrix is not invertible (i.e. inconsistent or underdefined)

    • inverseAccurately

      public abstract Matrix inverseAccurately()
      Creates and returns a new Matrix instance containing the inversion of this instance.
      Computes the inversion of the matrix by solving the equation AX = E, creates and returns a new Matrix containing the found inversion. Uses an iterative refinement to achieve a more accurate solution to the equation. The exact subtype of the returned matrix is the same as that of this instance. If the matrix is not invertible (i.e. inconsistent or underdefined), throws IllegalArgumentException with a relevant message and sets internal variable errorCode, whose value can be obtained using method getErrorCode().
      Returns:
      a new Matrix containing the inversion of the given matrix.
      Throws:
      IllegalArgumentException - if the matrix is not invertible (i.e. inconsistent or underdefined)

    • transpose

      public abstract Matrix transpose()
      Creates and returns a new Matrix instance containing the transposition of this instance.
      Computes the transposition of the matrix, creates and returns a new Matrix containing the found transposition.
      The exact subtype of the returned matrix is the same as that of this instance.
      Returns:
      a new Matrix containing the transposition of the given matrix.

    • unity

      public abstract Matrix unity()
      Creates and returns a new Matrix instance containing a unity matrix of the same size as the source matrix.
      The exact subtype of the returned matrix is the same as that of this instance.
      Returns:
      a new Matrix containing the unity matrix of the same size as this Matrix

    • multiply

      public abstract Matrix multiply(Matrix factor)
      Multiplies this instance of Matrix by the matrix passed in as the factor argument, creates and returns a new matrix containing the product. The exact subtype of the returned matrix is the same as that of this instance. If the size of the factor does not match the size of the source matrix, throws IllegalArgumentException with a relevant message.
      Parameters:
      factor - a matrix to multiply this instance by
      Returns:
      a new Matrix representing the product
      Throws:
      IllegalArgumentException - if the size of the argument does not match the size of this instance
      NullPointerException - if the argument is null

    • multiply

      public abstract Matrix multiply(double[][] factor)
      Multiplies this instance of Matrix by the factor passed in as a two-dimentional double array, and creates and returns a new matrix containing the product. The exact subtype of the returned matrix is the same as that of this instance.
      If the passed-in array is non-square, or its size does not match the size of this instance of the matrix, or matrixB contains non-numeric values (NaN or Infinity), throws IllegalArgumentException with a relevant message.
      Parameters:
      factor - two-dimentional double array representing a matrix to multiply this instance by
      Returns:
      a new Matrix representing the product
      Throws:
      IllegalArgumentException - if the passed-in array is non-square, or its size does not match the size of this instance of the matrix, or matrixB contains non-numeric values (NaN or Infinity)
      NullPointerException - if the argument is null

    • multiply

      public abstract Matrix multiply(Number[][] factor)
      Multiplies this instance of Matrix by the factor passed in as a two-dimentional array of Numbers, and creates and returns a new matrix containing the product. The exact subtype of the returned matrix is the same as that of this instance.
      If the passed-in array is non-square, or its size does not match the size of this instance of the matrix, or matrixB contains non-numeric values (NaN or Infinity) or null, throws IllegalArgumentException with a relevant message.
      Parameters:
      factor - two-dimentional array of Number representing the matrix to multiply this instance by
      Returns:
      a new Matrix representing the product
      Throws:
      IllegalArgumentException - if the passed-in array is non-square, or its size does not match the size of this instance of the matrix, or matrixB contains non-numeric values (NaN or Infinity) or null
      NullPointerException - if the argument is null

    • multiply

      public abstract Number[] multiply(double[] vector)
      Multiplies this instance of Matrix by a vector passed in as an array of doubles, and returns an array of Number values containing the product. The exact type of the elements of the returned array depends on the particular subtype of the Matrix.
      If the length of the vector does not match the size of the source matrix, or the argument contains non-numeric values (NaN or Infinity), throws IllegalArgumentException with a relevant message.
      Parameters:
      vector - the vector to multiply the matrix by.
      Returns:
      an array of Number values containing the product.
      Throws:
      IllegalArgumentException - if the length of the array does not match the size of the matrix, or the argument contains non-numeric values (NaN or Infinity).
      NullPointerException - if the argument is null

    • multiply

      public abstract Number[] multiply(Number[] vector)
      Multiplies this instance of Matrix by a vector passed in as an array of Number values and returns an array of Number values containing the product. The exact type of the elements of the returned array depends on the particular subtype of the Matrix.
      If the length of the vector does not match the size of the source matrix, or the argument contains non-numeric values (NaN or Infinity) or null, throws IllegalArgumentException with a relevant message.
      Parameters:
      vector - the vector to multiply the matrix by.
      Returns:
      an array of Number values containing the product.
      Throws:
      IllegalArgumentException - if the length of the array does not match the size of the matrix, or the argument contains non-numeric values (NaN or Infinity) or null
      NullPointerException - if the argument is null

    • multiply

      public abstract Matrix multiply(double scalar)
      Multiplies this instance of Matrix by a scalar factor scalar passed in as a double parameter, and creates and returns a new matrix containing the product. The exact subtype of the returned matrix is the same as that of this instance. If the argument is a non-numeric value (NaN or Infinity), throws IllegalArgumentException.
      Parameters:
      scalar - a double value to multiply this matrix by.
      Returns:
      a new Matrix containing the product of the source matrix and the given scalar.
      Throws:
      IllegalArgumentException - if the argument is NaN or Infinity.

    • multiply

      public abstract Matrix multiply(Number scalar)
      Multiplies this instance of Matrix by a scalar factor scalar passed in as a Number parameter, and creates and returns a new matrix containing the product. The exact subtype of the returned matrix is the same as that of this instance.
      If the argument is a non-numeric value (NaN or Infinity) or null, throws IllegalArgumentException.
      Parameters:
      scalar - a Number value to multiply this matrix by.
      Returns:
      a new Matrix containing the product of the source matrix and the given scalar.
      Throws:
      IllegalArgumentException - if the argument is NaN, Infinity or null.
      NullPointerException - if the argument is null

    • add

      public abstract Matrix add(Matrix matrixB)
      Adds the given matrixB to this matrix and returns the sum.
      Computes the sum of this matrix and the Matrix passed in, and creates and returns a new Matrix containing the found sum. The exact subtype of the returned matrix is the same as that of this instance. If the size of the matrixB does not match the size of this instance of the matrix, throws IllegalArgumentException with a relevant message.
      Parameters:
      matrixB - the matrix to add to the source matrix.
      Returns:
      a new Matrix containing the sum of the two matrices.
      Throws:
      IllegalArgumentException - if the size of the matrixB does not match the size of this instance.
      NullPointerException - if the argument is null

    • add

      public abstract Matrix add(double[][] matrixB)
      Adds the given matrixB passed in as a two-dimentional array of doubles to this matrix and returns the sum.
      Computes the sum of this matrix and the matrix passed in, and creates and returns a new Matrix containing the found sum. The exact subtype of the returned matrix is the same as that of this instance.
      If the passed-in array is non-square, or its size does not match the size of this instance of the matrix, or the argument contains non-numeric values (NaN or Infinity), throws IllegalArgumentException with a relevant message.
      Parameters:
      matrixB - the matrix to add to the source matrix.
      Returns:
      a new Matrix containing the sum of the two matrices.
      Throws:
      IllegalArgumentException - if the passed-in array is non-square, or its size does not match the size of this instance, or the argument contains non-numeric values (NaN or Infinity).
      NullPointerException - if the argument is null

    • add

      public abstract Matrix add(Number[][] matrixB)
      Adds the given matrixB passed in as a two-dimentional array of Number to this matrix and returns the sum.
      Computes the sum of this matrix and the matrix passed in, and creates and returns a new Matrix containing the found sum. The exact subtype of the returned matrix is the same as that of this instance.
      If the passed-in array is non-square, or its size does not match the size of this instance of the matrix, or the argument contains non-numeric values (NaN or Infinity) or null, throws IllegalArgumentException with a relevant message.
      Parameters:
      matrixB - the matrix to add to the source matrix.
      Returns:
      a new Matrix containing the sum of the two matrices.
      Throws:
      IllegalArgumentException - if the passed-in array is non-square, or its size does not match the size of this instance, or the argument contains non-numeric values (NaN or Infinity), or null.
      NullPointerException - if the argument is null

    • subtract

      public abstract Matrix subtract(Matrix matrixB)
      Subtracts the given matrixB from this matrix and returns the difference.
      Computes the difference of this matrix and the Matrix passed in, and creates and returns a new Matrix containing the found difference. The exact subtype of the returned matrix is the same as that of this instance. If the size of the matrixB does not match the size of this instance of the matrix, throws IllegalArgumentException with a relevant message.
      Parameters:
      matrixB - the matrix to subtract from the source matrix.
      Returns:
      a new Matrix containing the difference of the two matrices.
      Throws:
      IllegalArgumentException - if the size of the matrixB does not match the size of this instance.
      NullPointerException - if the argument is null

    • subtract

      public abstract Matrix subtract(double[][] matrixB)
      Subtracts the given matrixB passed in as a two-dimentional array of doubles from this matrix and returns the difference.
      Computes the difference of this matrix and the matrix passed in, creates and returns a new Matrix containing the found difference. The exact subtype of the returned matrix is the same as that of this instance.
      If the passed-in array is non-square, or its size does not match the size of this instance of the matrix, or the argument contains non-numeric values (NaN or Infinity), throws IllegalArgumentException with a relevant message.
      Parameters:
      matrixB - the matrix to subtract from the source matrix.
      Returns:
      a new Matrix containing the difference of the two matrices.
      Throws:
      IllegalArgumentException - if the passed-in array is non-square, or its size does not match the size of this instance, or the argument contains non-numeric values (NaN or Infinity).
      NullPointerException - if the argument is null

    • subtract

      public abstract Matrix subtract(Number[][] matrixB)
      Subtracts the given matrixB passed in as a two-dimentional array of Number from this matrix and returns the difference.
      Computes the difference of this matrix and the matrix passed in, creates and returns a new Matrix containing the found difference. The exact subtype of the returned matrix is the same as that of this instance.
      If the passed-in array is non-square, or its size does not match the size of this instance of the matrix, or the argument contains non-numeric values (NaN or Infinity) or null, throws IllegalArgumentException with a relevant message.
      Parameters:
      matrixB - the matrix to subtract from the source matrix.
      Returns:
      a new Matrix containing the difference of the two matrices.
      Throws:
      IllegalArgumentException - if the passed-in array is non-square, or its size does not match the size of this instance, or the argument contains non-numeric values (NaN or Infinity) or null.
      NullPointerException - if the argument is null

    • determinant

      public abstract Number determinant()
      Computes the determinant of the matrix and returns its value as a Number value.
      The particular type of the returned Number depends on the exact subtype of this instance of Matrix (it is double for DoubleMatrix, Quadruple for QuadrupleMatrix, and BigDecimal for BigDecimalMatrix).
      Returns:
      the value of the determinant of the given Matrix

    • determinantAsDouble

      public abstract double determinantAsDouble()
      Computes the determinant of the matrix and returns its value as a double value.
      Returns:
      the value of the determinant of the given Matrix

    • determinantAsQuadruple

      public abstract Quadruple determinantAsQuadruple()
      Computes the determinant of the matrix and returns its value as a Quadruple value. The precision of the result depends on the particular subtype of the instance.
      Returns:
      the value of the determinant of the given Matrix

    • determinantAsBigDecimal

      public abstract BigDecimal determinantAsBigDecimal()
      Computes the determinant of the matrix and returns its value as a BigDecimal value. The precision of the result depends on the particular subtype of the instance.
      Returns:
      the value of the determinant of the given Matrix

    • norm

      public abstract Number norm()
      Computes the row-based norm of the matrix, ║A║∞, and returns its value as a Number value.
      The particular type of the returned Number depends on the exact subtype of this instance of Matrix (it is double for DoubleMatrix, Quadruple for QuadrupleMatrix, and BigDecimal for BigDecimalMatrix).
      Returns:
      the value of the norm of the given Matrix

    • normAsDouble

      public abstract double normAsDouble()
      Computes the row-based norm of the matrix, ║A║∞, and returns its value as a double value.
      Returns:
      the value of the norm of the given Matrix

    • normAsQuadruple

      public abstract Quadruple normAsQuadruple()
      Computes the row-based norm of the matrix, ║A║∞, and returns its value as a Quadruple value. The precision of the result depends on the particular subtype of the instance.
      Returns:
      the value of the norm of the given Matrix

    • normAsBigDecimal

      public abstract BigDecimal normAsBigDecimal()
      Computes the row-based norm of the matrix, ║A║∞, and returns its value as a BigDecimal value. The precision of the result depends on the particular subtype of the instance.
      Returns:
      the value of the norm of the given Matrix

    • cond

      public abstract double cond()
      Computes the condition number of the matrix, ║A║•║A-1║, and returns its value as a double value.
      For non-invertible matrices returns Double.POSITIVE_INFINITY.
      Returns:
      the value of the condition number of the given Matrix, or Double.POSITIVE_INFINITY for non-invertible matrices