Package com.irurueta.algebra

Class SingularValueDecomposer

java.lang.Object
com.irurueta.algebra.Decomposer
com.irurueta.algebra.SingularValueDecomposer
public class SingularValueDecomposer extends Decomposer
Computes Singular Value matrix decomposition, which consists on factoring provided input matrix into three factors consisting of 2 unary matrices and 1 diagonal matrix containing singular values, following next expression: A = U * S * V'. Where A is provided input matrix of size m-by-n, U is an m-by-n unary matrix, S is an n-by-n diagonal matrix containing singular values, and V' denotes the transpose/conjugate of V and is an n-by-n unary matrix, for m < n.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_MAX_ITERS
    Constant defining default number of iterations to obtain convergence on singular value estimation.
    private final double
    eps
    Contains epsilon value, which indicates an estimation of numerical precision given by this machine.
    static final double
    EPS
    Constant defining machine precision.
    private int
    maxIters
    Member containing maximum number of iterations to obtain convergence of singular values estimation.
    static final int
    MIN_ITERS
    Constant defining minimum number of iterations allowed to obtain convergence on singular value estimation.
    static final double
    MIN_THRESH
    Constant defining minimum allowed value as threshold to determine whether a singular value is negligible or not.
    private double
    tsh
    Contains threshold used to determine whether a singular value can be neglected or not due to numerical precision errors.
    private Matrix
    u
    Internal storage of U.
    private Matrix
    v
    Internal storage of V.
    private double[]
    w
    Internal storage of singular values.

    Fields inherited from class com.irurueta.algebra.Decomposer

    inputMatrix, locked

  • Constructor Summary

    Constructors
    Constructor
    Description
    SingularValueDecomposer()
    Constructor of this class.
    SingularValueDecomposer(int maxIters)
    Constructor of this class.
    SingularValueDecomposer(Matrix inputMatrix)
    Constructor of this class.
    SingularValueDecomposer(Matrix inputMatrix, int maxIters)
    Constructor of this class.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    decompose()
    This method computes Singular Value matrix decomposition, which consists on factoring provided input matrix into three factors consisting of 2 unary matrices and 1 diagonal matrix containing singular values, following next expression: A = U * S * V'.
    double
    getConditionNumber()
    Returns the condition number of provided input matrix found after decomposition.
    DecomposerType
    getDecomposerType()
    Returns decomposer type corresponding to Singular Value decomposition.
    int
    getMaxIterations()
    Returns maximum number of iterations to be done in order to obtain convergence of singular values when computing input matrix Singular Value Decomposition.
    double
    getNegligibleSingularValueThreshold()
    Returns threshold to be used for determining whether a singular value is negligible or not.
    double
    getNorm2()
    Returns the 2-norm of provided input matrix, which is equal to the highest singular value found after decomposition.
    int
    getNullity()
    Returns effective numerical matrix nullity.
    int
    getNullity(double singularValueThreshold)
    Returns effective numerical matrix nullity.
    Matrix
    getNullspace()
    Returns matrix containing null-space of provided input matrix, which spans a subspace of dimension equal to the nullity of input matrix.
    Matrix
    getNullspace(double singularValueThreshold)
    Returns matrix containing null-space of provided input matrix, which spans a subspace of dimension equal to the nullity of input matrix.
    void
    getNullspace(double singularValueThreshold, Matrix nullspace)
    Sets into provided matrix null-space of provided input matrix, which spans a subspace of dimension equal to the nullity of input matrix.
    void
    getNullspace(Matrix nullspace)
    Sets into provided matrix null-space of provided input matrix, which spans a subspace of dimension equal to the nullity of input matrix.
    Matrix
    getRange()
    Return matrix containing Range space of provided input matrix, which spans a subspace of dimension equal to the rank of input matrix.
    Matrix
    getRange(double singularValueThreshold)
    Returns matrix containing Range space of provided input matrix, which spans a subspace of dimension equal to the rank of input matrix.
    void
    getRange(double singularValueThreshold, Matrix range)
    Sets into provided range matrix the Range space of provided input matrix, which spans a subspace of dimension equal to the rank of input matrix.
    void
    getRange(Matrix range)
    Sets into provided range matrix the Range space of provided input matrix, which spans a subspace of dimension equal to the rank of input matrix.
    int
    getRank()
    Returns effective numerical matrix rank.
    int
    getRank(double singularValueThreshold)
    Returns effective numerical matrix rank.
    double
    getReciprocalConditionNumber()
    Returns the inverse of the condition number, i.e. 1.0 / condition number.
    double[]
    getSingularValues()
    Returns a new vector instance containing all singular values after decomposition.
    Matrix
    getU()
    Returns a new matrix instance containing the left singular vector (U factor) from Singular Value matrix decomposition, which consists on decomposing a matrix using the following expression: A = U * S * V'.
    Matrix
    getV()
    Returns a new matrix instance containing the right singular vectors (V factor) from Singular Value matrix decomposition, which consists on decomposing a matrix using the following expression: A = U * S * V', Where A is provided input matrix of size m-by-n and V' denotes the transpose/conjugate of V, which is an n-by-n unary matrix for m < n.
    Matrix
    getW()
    Returns a new diagonal matrix instance containing all singular values on its diagonal after Singular Value matrix decomposition, which consists on decomposing a matrix using the following expression: A = U * S * V'.
    void
    getW(Matrix m)
    Copies diagonal matrix into provided instance containing all singular values on its diagonal after Singular Value matrix decomposition, which consists on decomposing a matrix using the following expression: A = U * S * V'.
    private void
    internalDecompose()
    This method is called internally by decompose(), and actually computes Singular Value Decomposition.
    private void
    internalGetNullspace(int nullity, double singularValueThreshold, Matrix nullspace)
    Internal method to copy null-space vector values into provided matrix.
    private void
    internalGetRange(int rank, double singularValueThreshold, Matrix range)
    Internal method to copy range space vector values into provided matrix.
    boolean
    isDecompositionAvailable()
    Returns boolean indicating whether decomposition has been computed and results can be retrieved.
    private double
    pythag(double a, double b)
    Computes norm of a vector of 2 components 'a' and 'b' as sqrt(pow(a, 2.0) + pow(b, 2.0)) without destructive underflow or overflow, that is when a or b are close to maximum or minimum values allowed by machine precision, computing the previous expression might lead to highly inaccurate results.
    private void
    reorder()
    Reorders singular values from maximal to minimal, and also reorders columns and rows of U and V to ensure that Singular Value Decomposition still remains valid.
    void
    setInputMatrix(Matrix inputMatrix)
    Sets reference to input matrix to be decomposed.
    void
    setMaxIterations(int maxIters)
    SSets maximum number of iterations to be done in order to obtain convergence of singular values when computing input matrix Singular Value Decomposition.
    private void
    setNegligibleSingularValueThreshold(double threshold)
    Sets threshold to be used to determine whether a singular value is negligible or not.
    private double
    sign(double a, double b)
    Returns a or -a depending on b sign.
    double[]
    solve(double[] b)
    Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution.
    double[]
    solve(double[] b, double singularValueThreshold)
    Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution.
    void
    solve(double[] b, double[] result)
    Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution.
    void
    solve(double[] b, double singularValueThreshold, double[] result)
    Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution.
    Matrix
    solve(Matrix b)
    Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution.
    Matrix
    solve(Matrix b, double singularValueThreshold)
    Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution.
    void
    solve(Matrix b, double singularValueThreshold, Matrix result)
    Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution.
    void
    solve(Matrix b, Matrix result)
    Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution.

    Methods inherited from class com.irurueta.algebra.Decomposer

    getInputMatrix, isLocked, isReady

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Field Details

    • DEFAULT_MAX_ITERS

      public static final int DEFAULT_MAX_ITERS
      Constant defining default number of iterations to obtain convergence on singular value estimation.
      See Also:

    • MIN_ITERS

      public static final int MIN_ITERS
      Constant defining minimum number of iterations allowed to obtain convergence on singular value estimation.
      See Also:

    • MIN_THRESH

      public static final double MIN_THRESH
      Constant defining minimum allowed value as threshold to determine whether a singular value is negligible or not.
      See Also:

    • EPS

      public static final double EPS
      Constant defining machine precision.
      See Also:

    • u

      private Matrix u
      Internal storage of U.

    • v

      private Matrix v
      Internal storage of V.

    • w

      private double[] w
      Internal storage of singular values.

    • eps

      private final double eps
      Contains epsilon value, which indicates an estimation of numerical precision given by this machine.

    • tsh

      private double tsh
      Contains threshold used to determine whether a singular value can be neglected or not due to numerical precision errors. This can be used to determine effective rank of input matrix.

    • maxIters

      private int maxIters
      Member containing maximum number of iterations to obtain convergence of singular values estimation. If singular values do not converge on provided maximum number of iterations, then a NoConvergenceException will be thrown when calling decompose() method.

  • Constructor Details

    • SingularValueDecomposer

      public SingularValueDecomposer()
      Constructor of this class.

    • SingularValueDecomposer

      public SingularValueDecomposer(int maxIters)
      Constructor of this class.
      Parameters:
      maxIters - Determines maximum number of iterations to be done when decomposing input matrix into singular values so that singular values converge properly.

    • SingularValueDecomposer

      public SingularValueDecomposer(Matrix inputMatrix)
      Constructor of this class.
      Parameters:
      inputMatrix - Reference to input matrix to be decomposed.

    • SingularValueDecomposer

      public SingularValueDecomposer(Matrix inputMatrix, int maxIters)
      Constructor of this class.
      Parameters:
      inputMatrix - Reference to input matrix to be decomposed.
      maxIters - Determines maximum number of iterations to be done when decomposing input matrix into singular value so that singular values converge properly.

  • Method Details

    • getDecomposerType

      public DecomposerType getDecomposerType()
      Returns decomposer type corresponding to Singular Value decomposition.
      Specified by:
      getDecomposerType in class Decomposer
      Returns:
      Decomposer type.

    • setInputMatrix

      public void setInputMatrix(Matrix inputMatrix) throws LockedException
      Sets reference to input matrix to be decomposed.
      Overrides:
      setInputMatrix in class Decomposer
      Parameters:
      inputMatrix - Reference to input matrix to be decomposed.
      Throws:
      LockedException - Exception thrown if attempting to call this method while this instance remains locked.

    • isDecompositionAvailable

      public boolean isDecompositionAvailable()
      Returns boolean indicating whether decomposition has been computed and results can be retrieved. Attempting to retrieve decomposition results when not available, will probably raise a NotAvailableException
      Specified by:
      isDecompositionAvailable in class Decomposer
      Returns:
      Boolean indicating whether decomposition has been computed and results can be retrieved.

    • decompose

      public void decompose() throws NotReadyException, LockedException, DecomposerException
      This method computes Singular Value matrix decomposition, which consists on factoring provided input matrix into three factors consisting of 2 unary matrices and 1 diagonal matrix containing singular values, following next expression: A = U * S * V'. Where A is provided input matrix of size m-by-n, U is an m-by-n unary matrix, S is an n-by-n diagonal matrix containing singular values, and V' denotes the transpose/conjugate of V and is an n-by-n unary matrix, for m < n. Note: Factors U, S and V will be accessible once Singular Value decomposition has been computed. Note: During execution of this method, Singular Value decomposition will be available and operations such as retrieving matrix factors, or computing rank of matrices among others will be able to be done. Attempting to call any of such operations before calling this method will raise a NotAvailableException because they require computation of SingularValue decomposition first.
      Specified by:
      decompose in class Decomposer
      Throws:
      NotReadyException - Exception thrown if attempting to call this method when this instance is not ready (i.e. no input matrix has been provided).
      LockedException - Exception thrown if this decomposer is already locked before calling this method. Notice that this method will actually lock this instance while it is being executed.
      DecomposerException - Exception thrown if for any reason decomposition fails while being executed, like when convergence of results cannot be obtained, etc.

    • getMaxIterations

      public int getMaxIterations()
      Returns maximum number of iterations to be done in order to obtain convergence of singular values when computing input matrix Singular Value Decomposition.
      Returns:
      Maximum number of iterations to obtain singular values convergence.

    • setMaxIterations

      public void setMaxIterations(int maxIters) throws LockedException
      SSets maximum number of iterations to be done in order to obtain convergence of singular values when computing input matrix Singular Value Decomposition. Note: This parameter should rarely be modified because default value is usually good enough. Note: If convergence of singular values is not achieved within provided maximum number of iterations, a DecomposerException will be thrown when calling decompose();
      Parameters:
      maxIters - Maximum number of iterations to obtain convergence of singular values. Provided value must be 1 or greater, otherwise an IllegalArgumentException will be thrown.
      Throws:
      LockedException - Exception thrown if attempting to call this method while this instance remains locked.
      IllegalArgumentException - Exception thrown if provided value for maxIters is out of valid range of values.

    • getNegligibleSingularValueThreshold

      public double getNegligibleSingularValueThreshold() throws NotAvailableException
      Returns threshold to be used for determining whether a singular value is negligible or not. This threshold can be used to consider a singular value as zero or not, since small singular values might appear in places where they should be zero because of rounding errors and machine precision. Singular values considered as zero determine aspects such as rank, nullability, null-space or range space.
      Returns:
      Threshold to be used for determining whether a singular value is negligible or not.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first.

    • getU

      public Matrix getU() throws NotAvailableException
      Returns a new matrix instance containing the left singular vector (U factor) from Singular Value matrix decomposition, which consists on decomposing a matrix using the following expression: A = U * S * V'. Where A is provided input matrix of size m-by-n and U is an m-by-n unary matrix for m < n.
      Returns:
      Matrix instance containing the left singular vectors from a Singular Value decomposition.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first.
      See Also:

    • getV

      public Matrix getV() throws NotAvailableException
      Returns a new matrix instance containing the right singular vectors (V factor) from Singular Value matrix decomposition, which consists on decomposing a matrix using the following expression: A = U * S * V', Where A is provided input matrix of size m-by-n and V' denotes the transpose/conjugate of V, which is an n-by-n unary matrix for m < n.
      Returns:
      Matrix instance containing the right singular vectors from a Singular Value decomposition.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first.
      See Also:

    • getSingularValues

      public double[] getSingularValues() throws NotAvailableException
      Returns a new vector instance containing all singular values after decomposition. Returned vector is equal to the diagonal of S matrix within expression: A = U * S * V' where A is provided input matrix and S is a diagonal matrix containing singular values on its diagonal.
      Returns:
      singular values.
      Throws:
      NotAvailableException - if decomposition has not yet been computed.

    • getW

      public void getW(Matrix m) throws NotAvailableException, WrongSizeException
      Copies diagonal matrix into provided instance containing all singular values on its diagonal after Singular Value matrix decomposition, which consists on decomposing a matrix using the following expression: A = U * S * V'. Where A is provided input matrix of size m-by-n and S is a diagonal matrix of size n-by-n for m < n.
      Parameters:
      m - matrix instance containing all singular values on its diagonal after execution of this method.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first.
      WrongSizeException - if provided matrix does not have size n-by-n.
      See Also:

    • getW

      public Matrix getW() throws NotAvailableException
      Returns a new diagonal matrix instance containing all singular values on its diagonal after Singular Value matrix decomposition, which consists on decomposing a matrix using the following expression: A = U * S * V'. Where A is provided input matrix of size m-by-n and S is a diagonal matrix of size n-by-n for m < n.
      Returns:
      Returned matrix instance containing all singular values on its diagonal.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first.
      See Also:

    • getNorm2

      public double getNorm2() throws NotAvailableException
      Returns the 2-norm of provided input matrix, which is equal to the highest singular value found after decomposition. This is also called the Ky Fan 1-norm. This norm is also equal to the square root of Frobenius norm of the squared provided input matrix. In other words: sqrt(norm(A' * A, 'fro')) in Matlab notation. Where A is provided input matrix and A' is its transpose, and hence A' * A can be considered the squared matrix of A, and Frobenius norm is defined as the square root of the sum of the squared elements of a matrix: sqr(sum(A(:).^2))
      Returns:
      The 2-norm of provided input matrix, which is equal to the highest singular value.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first.
      See Also:

    • getConditionNumber

      public double getConditionNumber() throws NotAvailableException
      Returns the condition number of provided input matrix found after decomposition. The condition number of a matrix measures the sensitivity of the solution of a system of linear equations to errors in the data. It gives an indication of the accuracy of the results from matrix inversion and the solution of a linear system of equations. A problem with a low condition number is said to be well-conditioned, whereas a problem with a high condition number is said to be ill-conditioned. The condition number is a property of a matrix and is not related to the algorithm or floating point accuracy of a machine to solve a linear system of equations or make matrix inversion. When solving a linear system of equations (A * X = b), one should think of the condition number as being (very roughly) the rate at which the solution x will change with respect to a change in b. Thus, if the condition number is large, even a small error in b may cause a large error in x. On the other hand, if the condition number is small then the error in x will not be much bigger than the error in b. One way to find the condition number is by using the ration of the maximal and minimal singular values of a matrix, which is what this method returns.
      Returns:
      The condition number of provided input matrix.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first.
      See Also:

    • getReciprocalConditionNumber

      public double getReciprocalConditionNumber() throws NotAvailableException
      Returns the inverse of the condition number, i.e. 1.0 / condition number. Hence, when reciprocal condition number is close to zero, input matrix will be ill-conditioned. For more information see getConditionNumber()
      Returns:
      Inverse of the condition number.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first.
      See Also:

    • getRank

      public int getRank(double singularValueThreshold) throws NotAvailableException
      Returns effective numerical matrix rank. By definition rank of a matrix can be found as the number of non-zero singular values of such matrix found after decomposition. However, rounding error and machine precision may lead to small but non-zero singular values in a rank deficient matrix. This method tries to cope with such rounding errors by taking into account only those non-negligible singular values to determine input matrix rank. The Rank-nullity theorem states that for a matrix A of size m-by-n then: rank(A) + nullity(A) = n Where A is input matrix and n is the number of columns of such matrix.
      Parameters:
      singularValueThreshold - Threshold used to determine whether a singular value is negligible or not.
      Returns:
      Effective numerical matrix rank.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first.
      IllegalArgumentException - Exception thrown if provided singular value threshold is negative. Returned singular values after decomposition are always positive, and hence, provided threshold should be a positive value close to zero.
      See Also:

    • getRank

      public int getRank() throws NotAvailableException
      Returns effective numerical matrix rank. By definition rank of a matrix can be found as the number of non-zero singular values of such matrix found after decomposition. However, rounding error and machine precision may lead to small but non-zero singular values in a rank deficient matrix. This method tries to cope with such rounding error by taking into account only those non-negligible singular values to determine input matrix rank. The Rank-nullity theorem states that for a matrix A of size m-by-n then: rank(A) + nullity(A) = n Where A is input matrix and n is number of columns of such matrix. Note: This method makes same actions as int getRank(double) except that singular value threshold is automatically computed by taking into account input matrix size, maximal singular value and machine precision. This threshold is good enough for most situations, and hence we discourage setting it manually.
      Returns:
      Effective numerical matrix rank.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first.
      See Also:

    • getNullity

      public int getNullity(double singularValueThreshold) throws NotAvailableException
      Returns effective numerical matrix nullity. By definition nullity of a matrix can be found as the number of zero or negligible singular values of provided input matrix after decomposition. Rounding error and machine precision may lead to small but non-zero singular values in a rank deficient matrix. This method tries to cope with such rounding error by taking into account only those negligible singular values to determine input matrix nullity. The Rank-nullity theorem states that for a matrix A of size m-by-n then: rank(A) + nullity(A) = n Where A is input matrix and n is number of columns of such matrix.
      Parameters:
      singularValueThreshold - Threshold used to determine whether a singular value is negligible or not.
      Returns:
      Effective numerical matrix nullity.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition.
      IllegalArgumentException - Exception thrown if provided singular value threshold is negative. Returned singular values after decomposition are always positive, and hence, provided threshold should be a positive value close to zero.
      See Also:

    • getNullity

      public int getNullity() throws NotAvailableException
      Returns effective numerical matrix nullity. By definition nullity of a matrix can be found as the number of zero or negligible singular values of provided input matrix after decomposition. Rounding error and machine precision may lead to small but non-zero singular values in a rank deficient matrix. This method tries to cope with such rounding error by taking into account only those negligible singular values to determine input matrix nullity. The Rank-nullity theorem states that for a matrix A of size m-by-n then: rank(A) + nullity(A) = n Where A is input matrix and n is number of columns of such matrix. Note: This method makes the same actions as int getNullity(double) except that singular value threshold is automatically computed by taking into account input matrix size, maximal singular value and machine precision. This threshold is good enough for most situations, and hence we discourage setting it manually.
      Returns:
      Effective numerical matrix nullity.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first.
      See Also:

    • getRange

      public void getRange(double singularValueThreshold, Matrix range) throws NotAvailableException
      Sets into provided range matrix the Range space of provided input matrix, which spans a subspace of dimension equal to the rank of input matrix. Range space is equal to the columns of U corresponding to non-negligible singular values.
      Parameters:
      singularValueThreshold - Threshold used to determine whether a singular value is negligible or not.
      range - Matrix containing Range space of provided input matrix.
      Throws:
      NotAvailableException - Exception thrown if input matrix has rank zero or also if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first and make sure that input matrix has non-zero rank.
      IllegalArgumentException - Exception thrown if provided singular value threshold is negative. Returned singular values after decomposition are always positive, and hence, provided threshold should be a positive near to zero value.

    • getRange

      public void getRange(Matrix range) throws NotAvailableException
      Sets into provided range matrix the Range space of provided input matrix, which spans a subspace of dimension equal to the rank of input matrix. Range space is equal to the columns of U corresponding to non-negligible singular values. This method performs same actions as getRange(double, Matrix) except that singular value threshold is automatically computed by taking into account input matrix size, maximal singular value and machine precision. This threshold is good enough for most situations, and hence we discourage setting it manually.
      Parameters:
      range - Matrix containing Range space of provided input matrix.
      Throws:
      NotAvailableException - Exception thrown if input matrix has rank zero or also if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first and make sure that input matrix has non-zero rank.
      IllegalArgumentException - Exception thrown if provided singular value threshold is negative. Returned singular values after decomposition are always positive, and hence, provided threshold should be a positive near to zero value.

    • getRange

      public Matrix getRange(double singularValueThreshold) throws NotAvailableException
      Returns matrix containing Range space of provided input matrix, which spans a subspace of dimension equal to the rank of input matrix. Range space is equal to the columns of U corresponding to non-negligible singular values.
      Parameters:
      singularValueThreshold - Threshold used to determine whether a singular value is negligible or not.
      Returns:
      Matrix containing Range space of provided input matrix.
      Throws:
      NotAvailableException - Exception thrown if input matrix has rank zero or also if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first and make sure that input matrix has non-zero rank.
      IllegalArgumentException - Exception thrown if provided singular value threshold is negative. Returned singular values after decomposition are always positive, and hence, provided threshold should be a positive near to zero value.

    • getRange

      public Matrix getRange() throws NotAvailableException
      Return matrix containing Range space of provided input matrix, which spans a subspace of dimension equal to the rank of input matrix. Range space is equal to the columns of U corresponding to non-negligible singular values. This method performs same actions as Matrix getRange(double) except that singular value threshold is automatically computed by taking into account input matrix size, maximal singular value and machine precision. This threshold is good enough for most situations, and hence we discourage setting it manually.
      Returns:
      Matrix containing Range space of provided input matrix
      Throws:
      NotAvailableException - Exception thrown if input matrix has rank zero or also if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first and make sure that input matrix has non-zero rank.

    • getNullspace

      public void getNullspace(double singularValueThreshold, Matrix nullspace) throws NotAvailableException
      Sets into provided matrix null-space of provided input matrix, which spans a subspace of dimension equal to the nullity of input matrix. Null-space is equal to the columns of V corresponding to negligible singular values.
      Parameters:
      singularValueThreshold - Threshold used to determine whether a singular value is negligible or not.
      nullspace - Matrix containing null-space of provided input matrix.
      Throws:
      NotAvailableException - Exception thrown if input matrix has full rank, and hence its nullity is zero, or also if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first and make sure that input matrix is rank deficient.
      IllegalArgumentException - Exception thrown if provided singular value threshold is negative. Returned singular values after decomposition are always positive, and hence, provided threshold should be a positive near to zero value.

    • getNullspace

      public void getNullspace(Matrix nullspace) throws NotAvailableException
      Sets into provided matrix null-space of provided input matrix, which spans a subspace of dimension equal to the nullity of input matrix. Null-space is equal to the columns of V corresponding to negligible singular values. This method performs same actions as getNullspace(double, Matrix) except that singular value threshold is automatically computed by taking into account input matrix size, maximal singular value and machine precision. This threshold is good enough for most situations, and hence we discourage setting it manually.
      Parameters:
      nullspace - Matrix containing null-space of provided input matrix.
      Throws:
      NotAvailableException - Exception thrown if input matrix has full rank, and hence its nullity is zero, or also if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first and make sure that input matrix is rank deficient.
      IllegalArgumentException - Exception thrown if provided singular value threshold is negative. Returned singular values after decomposition are always positive, and hence, provided threshold should be a positive near to zero value.

    • getNullspace

      public Matrix getNullspace(double singularValueThreshold) throws NotAvailableException
      Returns matrix containing null-space of provided input matrix, which spans a subspace of dimension equal to the nullity of input matrix. Null-space is equal to the columns of V corresponding to negligible singular values.
      Parameters:
      singularValueThreshold - Threshold used to determine whether a singular value is negligible or not.
      Returns:
      Matrix containing null-space of provided input matrix.
      Throws:
      NotAvailableException - Exception thrown if input matrix has full rank, and hence its nullity is zero, or also if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first and make sure that input matrix is rank deficient.
      IllegalArgumentException - Exception thrown if provided singular value threshold is negative. Returned singular values after decomposition are always positive, and hence, provided threshold should be a positive near to zero value.

    • getNullspace

      public Matrix getNullspace() throws NotAvailableException
      Returns matrix containing null-space of provided input matrix, which spans a subspace of dimension equal to the nullity of input matrix. Null-space is equal to the columns of V corresponding to negligible singular values.
      Returns:
      Matrix containing null-space of provided input matrix. This method performs same actions as Matrix getNullspace(double) except that singular value threshold is automatically computed by taking into account input matrix size, maximal singular value and machine precision. This threshold is good enough for most situations, and hence we discourage setting it manually.
      Throws:
      NotAvailableException - Exception thrown if input matrix has full rank, and hence its nullity is zero, or also if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first and make sure that input matrix is rank deficient.

    • solve

      public void solve(Matrix b, double singularValueThreshold, Matrix result) throws NotAvailableException, WrongSizeException
      Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution. Where A is the input matrix provided for Singular Value decomposition, X is the solution to the system of equations, and B is the parameters matrix. Note: This method can be reused for different b matrices without having to recompute Singular Value decomposition on the same input matrix. Note: Provided b matrix must have the same number of rows as provided input matrix A, otherwise a WrongSizeException will be raised. Note: In order to execute this method, a Singular Value decomposition must be available, otherwise a NotAvailableException will be raised. In order to avoid this exception call decompose() method first. Note: Provided result matrix will be resized if needed
      Parameters:
      b - Parameters matrix that determine a linear system of equations. Provided matrix must have the same number of rows as provided input matrix for Singular Value decomposition. Besides, each column on parameters matrix will represent a new system of equations, whose solution will be returned on appropriate column as an output of this method.
      singularValueThreshold - Threshold used to determine whether a singular value is negligible or not.
      result - Matrix containing least squares solution of linear system of equations on each column for each column of provided parameters matrix b.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first.
      WrongSizeException - Exception thrown if provided parameters matrix (b) does not have the same number of rows as input matrix being Singular Value decomposed.
      IllegalArgumentException - Exception thrown if provided singular value threshold is lower than minimum allowed value (MIN_THRESH).
      See Also:

    • solve

      public void solve(Matrix b, Matrix result) throws NotAvailableException, WrongSizeException
      Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution. Where A is the input matrix provided for Singular Value decomposition, X is the solution to the system of equations, and B is the parameter matrix. Note: This method can be reused for different b matrices without having to recompute Singular Value decomposition on the same input matrix. Note: Provided b matrix must have the same number of rows as provided input matrix A, otherwise a WrongSizeException will be raised. Note: In order to execute this method, a Singular Value decomposition must be available, otherwise a NotAvailableException will be raised. In order to avoid this exception call decompose() method first. Note: This method performs same actions as Matrix solve(Matrix, double) except that singular value threshold is automatically computed by taking into account input matrix size, maximal singular value and machine precision. This threshold is good enough for most situations, and hence we discourage setting it manually. Note: Provided result matrix will be resized if needed
      Parameters:
      b - Parameters matrix that determines a linear system of equations. Provided matrix must have the same number of rows as provided input matrix for Singular Value decomposition. Besides, each column on parameters matrix will represent a new system of equations, whose solution will be returned on appropriate column as an output of this method.
      result - Matrix containing least squares solution of linear system of equations on each column for each column of provided parameters matrix b.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first.
      WrongSizeException - Exception thrown if provided parameters matrix (b) does not have the same number of rows as input matrix being Singular Value decomposed.
      See Also:

    • solve

      public Matrix solve(Matrix b, double singularValueThreshold) throws NotAvailableException, WrongSizeException
      Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution. Where A is the input matrix provided for Singular Value decomposition, X is the solution to the system of equations, and B is the parameter matrix. Note: This method can be reused for different b matrices without having to recompute Singular Value decomposition on the same input matrix. Note: Provided b matrix must have the same number of rows as provided input matrix A, otherwise a WrongSizeException will be raised. Note: In order to execute this method, a Singular Value decomposition must be available, otherwise a NotAvailableException will be raised. In order to avoid this exception call decompose() method first.
      Parameters:
      b - Parameters matrix that determine a linear system of equations. Provided matrix must have the same number of rows as provided input matrix for Singular Value decomposition. Besides, each column on parameters matrix will represent a new system of equations, whose solution will be returned on appropriate column as an output of this method.
      singularValueThreshold - Threshold used to determine whether a singular value is negligible or not.
      Returns:
      Matrix containing least squares solution of linear system of equations on each column for each column of provided parameters matrix b.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first.
      WrongSizeException - Exception thrown if provided parameters matrix (b) does not have the same number of rows as input matrix being Singular Value decomposed.
      IllegalArgumentException - Exception thrown if provided singular value threshold is lower than minimum allowed value (MIN_THRESH).
      See Also:

    • solve

      public Matrix solve(Matrix b) throws NotAvailableException, WrongSizeException
      Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution. Where A is the input matrix provided for Singular Value decomposition, X is the solution to the system of equations, and B is the parameter matrix. Note: This method can be reused for different b matrices without having to recompute Singular Value decomposition on the same input matrix. Note: Provided b matrix must have the same number of rows as provided input matrix A, otherwise a WrongSizeException will be raised. Note: In order to execute this method, a Singular Value decomposition must be available, otherwise a NotAvailableException will be raised. In order to avoid this exception call decompose() method first. Note: This method performs same actions as Matrix solve(Matrix, double) except that singular value threshold is automatically computed by taking into account input matrix size, maximal singular value and machine precision. This threshold is good enough for most situations, and hence we discourage setting it manually.
      Parameters:
      b - Parameters matrix that determines a linear system of equations. Provided matrix must have the same number of rows as provided input matrix for Singular Value decomposition. Besides, each column on parameters matrix will represent a new system of equations, whose solution will be returned on appropriate column as an output of this method.
      Returns:
      Matrix containing least squares solution of linear system of equations on each column for each column of provided parameters matrix b.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing Singular Value decomposition. To avoid this exception call decompose() method first.
      WrongSizeException - Exception thrown if provided parameters matrix (b) does not have the same number of rows as input matrix being Singular Value decomposed.
      See Also:

    • solve

      public void solve(double[] b, double singularValueThreshold, double[] result) throws NotAvailableException, WrongSizeException
      Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution. Where A i s the input matrix provided for Singular Value decomposition, X is the solution to the system of equations, and B is the parameters array. Note: This method can be reused for different b arrays without having to recompute Singular Value decomposition on the same input matrix. Note: Provided b array must have the same length as the number of rows on provided input matrix A, otherwise a WrongSizeException will be raised. Note: In order to execute this method, a Singular Value decomposition must be available, otherwise a NotAvailableException will be raised. In order to avoid this exception call decompose() method first.
      Parameters:
      b - Parameters array that determines a linear system of equations. Provided array must have the same length as number of rows on provided input matrix for Singular Value decomposition.
      singularValueThreshold - Threshold used to determine whether a singular value is negligible or not.
      result - Vector where least squares solution of linear system of equations for provided parameters array b will be stored.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing SingularValue decomposition. To avoid this exception call decompose() method first.
      WrongSizeException - Exception thrown if provided parameters array (b) does not have the same length as number of rows on input matrix being Singular Value decomposed or if provided result array does not have the same length as the number of columns on input matrix.
      IllegalArgumentException - Exception thrown if provided singular value threshold is lower than minimum allowed value (MIN_THRESH).
      See Also:

    • solve

      public void solve(double[] b, double[] result) throws NotAvailableException, WrongSizeException
      Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution. Where A i s the input matrix provided for Singular Value decomposition, X is the solution to the system of equations, and B is the parameters array. Note: This method can be reused for different b arrays without having to recompute Singular Value decomposition on the same input matrix. Note: Provided b array must have the same length as the number of rows on provided input matrix A, otherwise a WrongSizeException will be raised. Note: In order to execute this method, a Singular Value decomposition must be available, otherwise a NotAvailableException will be raised. In order to avoid this exception call decompose() method first. Note: this method performs same actions as double[] solve(double[], double) except that singular value threshold is automatically computed by taking into account input matrix size, maximal singular value and machine precision. This threshold is good enough for most situations, and hence we discourage setting it manually.
      Parameters:
      b - Parameters array that determines a linear system of equations. Provided array must have the same length as number of rows on provided input matrix for Singular Value decomposition.
      result - Vector where least squares solution of linear system of equations for provided parameters array b will be stored.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing SingularValue decomposition. To avoid this exception call decompose() method first.
      WrongSizeException - Exception thrown if provided parameters array (b) does not have the same length as number of rows on input matrix being Singular Value decomposed or if provided result array does not have the same length as the number of columns on input matrix.
      IllegalArgumentException - Exception thrown if provided singular value threshold is lower than minimum allowed value (MIN_THRESH).
      See Also:

    • solve

      public double[] solve(double[] b, double singularValueThreshold) throws NotAvailableException, WrongSizeException
      Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution. Where A i s the input matrix provided for Singular Value decomposition, X is the solution to the system of equations, and B is the parameters array. Note: This method can be reused for different b arrays without having to recompute Singular Value decomposition on the same input matrix. Note: Provided b array must have the same length as the number of rows on provided input matrix A, otherwise a WrongSizeException will be raised. Note: In order to execute this method, a Singular Value decomposition must be available, otherwise a NotAvailableException will be raised. In order to avoid this exception call decompose() method first.
      Parameters:
      b - Parameters array that determines a linear system of equations. Provided array must have the same length as number of rows on provided input matrix for Singular Value decomposition.
      singularValueThreshold - Threshold used to determine whether a singular value is negligible or not.
      Returns:
      Vector containing least squares solution of linear system of equations for provided parameters array b.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing SingularValue decomposition. To avoid this exception call decompose() method first.
      WrongSizeException - Exception thrown if provided parameters array (b) does not have the same length as number of rows on input matrix being Singular Value decomposed.
      IllegalArgumentException - Exception thrown if provided singular value threshold is lower than minimum allowed value (MIN_THRESH).
      See Also:

    • solve

      public double[] solve(double[] b) throws NotAvailableException, WrongSizeException
      Solves a linear system of equations of the following form: A * X = B using the pseudo-inverse to find the least squares solution. Where A i s the input matrix provided for Singular Value decomposition, X is the solution to the system of equations, and B is the parameters array. Note: This method can be reused for different b arrays without having to recompute Singular Value decomposition on the same input matrix. Note: Provided b array must have the same length as the number of rows on provided input matrix A, otherwise a WrongSizeException will be raised. Note: In order to execute this method, a Singular Value decomposition must be available, otherwise a NotAvailableException will be raised. In order to avoid this exception call decompose() method first. Note: this method performs same actions as double[] solve(double[], double) except that singular value threshold is automatically computed by taking into account input matrix size, maximal singular value and machine precision. This threshold is good enough for most situations, and hence we discourage setting it manually.
      Parameters:
      b - Parameters array that determines a linear system of equations. Provided array must have the same length as number of rows on provided input matrix for Singular Value decomposition.
      Returns:
      Vector containing least squares solution of linear system of equations for provided parameters array b.
      Throws:
      NotAvailableException - Exception thrown if attempting to call this method before computing SingularValue decomposition. To avoid this exception call decompose() method first.
      WrongSizeException - Exception thrown if provided parameters array (b) does not have the same length as number of rows on input matrix being Singular Value decomposed.
      See Also:

    • internalDecompose

      private void internalDecompose() throws NoConvergenceException
      This method is called internally by decompose(), and actually computes Singular Value Decomposition. However, algorithm implemented in this algorithm does not ensure that singular values are ordered from maximal to minimal, and hence reorder() method is called next within decompose() as well.
      Throws:
      NoConvergenceException - Exception thrown if singular value estimation does not converge within provided number of maximum iterations.

    • reorder

      private void reorder()
      Reorders singular values from maximal to minimal, and also reorders columns and rows of U and V to ensure that Singular Value Decomposition still remains valid.

    • setNegligibleSingularValueThreshold

      private void setNegligibleSingularValueThreshold(double threshold)
      Sets threshold to be used to determine whether a singular value is negligible or not. This threshold can be used to consider a singular value as zero or not, since small singular values might appear in places where they should be zero because of rounding errors and machine precision. Singular values considered as zero determine aspects such as rank, nullability, null-space or range space.
      Parameters:
      threshold - Threshold to be used to determine whether a singular value is negligible or not.

    • pythag

      private double pythag(double a, double b)
      Computes norm of a vector of 2 components 'a' and 'b' as sqrt(pow(a, 2.0) + pow(b, 2.0)) without destructive underflow or overflow, that is when a or b are close to maximum or minimum values allowed by machine precision, computing the previous expression might lead to highly inaccurate results. This method implements previous expression to avoid this effect as much as possible and increase accuracy.
      Parameters:
      a - 1st value
      b - 2nd value
      Returns:
      Norm of (a, b).

    • sign

      private double sign(double a, double b)
      Returns a or -a depending on b sign. If b is positive, this method returns "a", otherwise it returns -a
      Parameters:
      a - 1st value
      b - 2nd value
      Returns:
      a or -a depending on b sign.

    • internalGetRange

      private void internalGetRange(int rank, double singularValueThreshold, Matrix range)
      Internal method to copy range space vector values into provided matrix. Provided matrix will be resized if needed
      Parameters:
      rank - Rank of range space
      singularValueThreshold - Threshold to determine whether a singular value is null
      range - Matrix where range space vector values are stored.

    • internalGetNullspace

      private void internalGetNullspace(int nullity, double singularValueThreshold, Matrix nullspace)
      Internal method to copy null-space vector values into provided matrix. Provided matrix will be resized if needed
      Parameters:
      nullity - Nullity of null-space
      singularValueThreshold - Threshold to determine whether a singular value is null
      nullspace - Matrix where null-space vector values are stored.