Class SVD<T extends MatrixMixin<T,?,?,?>>

java.lang.Object
org.flag4j.linalg.decompositions.Decomposition<T>
org.flag4j.linalg.decompositions.svd.SVD<T>
Type Parameters:
T - The type of the matrix to compute the singular value decomposition of.
Direct Known Subclasses:
ComplexSVD, RealSVD
public abstract class SVD<T extends MatrixMixin<T,?,?,?>> extends Decomposition<T>

This abstract class specifies methods for computing the singular value decomposition (SVD) of a matrix.

That is, decomposes a rectangular matrix \( M \) into \( M=U\Sigma V^{H} \) where \( U \) and \( V \) are unitary matrices whose columns are the left and right singular vectors of \( M \) and \( \Sigma \) is a rectangular diagonal matrix containing the singular values of \( M \).

The SVD may also be used to compute the (numerical) rank of the matrix using getRank().

The SVD proceeds by an iterative algorithm with possible random behavior. For reproducibility, constructors support specifying a seed for the pseudo-random number generator.

Usage:

The decomposition workflow typically follows these steps:
  1. Instantiate a concrete instance of SVD.
  2. Call decompose(MatrixMixin) to perform the factorization.
  3. Retrieve the resulting matrices using getU() and getS().

Efficiency Considerations:

If singular vectors are not required, setting computeUV = false may improve performance.
See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected boolean
    computeUV
    Flag which indicates if the singular vectors should be computed in addition to the singular values.
    protected int
    rank
    The rank of the matrix being decomposed.
    protected boolean
    reduced
    Flag which indicates if the reduced (or full) SVD should be computed.
    protected Matrix
    S
    The rectangular diagonal \( \Sigma \) corresponding to \( M=U\Sigma V^{H} \) in the SVD.
    protected long
    seed
    Seed to use in pseudo-random number generator.
    protected T
    U
    The unitary matrix \( U \) corresponding to \( M=U\Sigma V^{H} \) in the SVD.
    protected boolean
    useSeed
    Flag indicating if seeding should be used in pseudo-random operations.
    protected T
    V
    The unitary matrix \( V \) corresponding to \( M=U\Sigma V^{H} \) in the SVD.

    Fields inherited from class org.flag4j.linalg.decompositions.Decomposition

    hasDecomposed

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    SVD(boolean computeUV, boolean reduced)
    Creates a decomposer to compute the Schur decomposition.
    protected
    SVD(boolean computeUV, boolean reduced, long seed)
    Creates a decomposer to compute the Schur decomposition.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected void
    computeRank(int rows, int cols, double[] singularValues)
    Computes the rank of the matrix being decomposed using the singular values of the matrix.
    SVD<T>
    decompose(T src)
    Applies decomposition to the source matrix.
    protected abstract void
    extractNormalizedCols(T singularVecs, int j)
    Extracts the singular vectors, normalizes them and sets the columns of \( U \) and \( V \) to be the left/right singular vectors.
    int
    getRank()
    Gets the rank of the last matrix decomposed.
    Matrix
    getS()
    Gets the diagonal matrix \( \Sigma \) corresponding to \( M=U\Sigma V^{H} \) in the SVD.
    Vector
    getSingularValues()
    Gets the singular values of the last matrix decomposed.
    T
    getU()
    Gets the unitary matrix \( U \) corresponding to \( M=U\Sigma V^{H} \) in the SVD.
    T
    getV()
    Gets the unitary matrix \( V \) corresponding to \( M=U\Sigma V^{H} \) in the SVD.
    protected abstract void
    initUV(Shape src, int cols)
    Initializes the unitary \( U \) and \( V \) matrices for the SVD.
    protected abstract T
    invDirectSum(T src)
    Computes the inverse direct sum of a matrix and its Hermitian transpose.
    protected abstract T
    makeEigenPairs(T B, double[] eigVals)
    Gets the eigen values and vectors of symmetric block matrix which corresponds to the singular values and vectors of the matrix being decomposed.
    protected abstract void
    makeEigenVals(T B, double[] eigVals)
    Gets the eigen values of the symmetric block matrix which corresponds to the singular values of the matrix being decomposed.

    Methods inherited from class org.flag4j.linalg.decompositions.Decomposition

    ensureHasDecomposed

    Methods inherited from class java.lang.Object

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

  • Field Details

    • seed

      protected long seed
      Seed to use in pseudo-random number generator.

    • useSeed

      protected boolean useSeed
      Flag indicating if seeding should be used in pseudo-random operations.
      • If true, then seeding will be used.
      • If false, then seeding will not be used.

    • computeUV

      protected boolean computeUV
      Flag which indicates if the singular vectors should be computed in addition to the singular values.

    • reduced

      protected boolean reduced
      Flag which indicates if the reduced (or full) SVD should be computed.

    • U

      protected T extends MatrixMixin<T,?,?,?> U
      The unitary matrix \( U \) corresponding to \( M=U\Sigma V^{H} \) in the SVD.

    • S

      protected Matrix S
      The rectangular diagonal \( \Sigma \) corresponding to \( M=U\Sigma V^{H} \) in the SVD.

    • V

      protected T extends MatrixMixin<T,?,?,?> V
      The unitary matrix \( V \) corresponding to \( M=U\Sigma V^{H} \) in the SVD.

    • rank

      protected int rank
      The rank of the matrix being decomposed. This is calculated as a byproduct of the decomposition.

  • Constructor Details

    • SVD

      protected SVD(boolean computeUV, boolean reduced)
      Creates a decomposer to compute the Schur decomposition.
      Parameters:
      computeUV - A flag which indicates if the unitary matrices \( U \) and \( V \) should be computed (i.e. the singular vectors).
      • If true, the \( U \) and \( V \) matrices will be computed.
      • If false, the \( U \) and \( V \) matrices will not be computed. If it is not needed, this may provide a performance improvement.
      reduced - Flag which indicates if the reduced (or full) SVD should be computed.
      • If true, reduced SVD is computed.
      • If false, the full SVD is computed.

    • SVD

      protected SVD(boolean computeUV, boolean reduced, long seed)
      Creates a decomposer to compute the Schur decomposition.
      Parameters:
      computeUV - A flag which indicates if the unitary matrices \( U \) and \( V \) should be computed (i.e. the singular vectors).
      • If true, the \( U \) and \( V \) matrices will be computed.
      • If false, the \( U \) and \( V \) matrices will not be computed. If it is not needed, this may provide a performance improvement.
      reduced - Flag which indicates if the reduced (or full) SVD should be computed.
      • If true, reduced SVD is computed.
      • If false, the full SVD is computed.
      seed - Seed to use in pseudo-random number generators. Setting this will allow for reproducibility between multiple calls with the same inputs.

  • Method Details

    • getU

      public T getU()
      Gets the unitary matrix \( U \) corresponding to \( M=U\Sigma V^{H} \) in the SVD.
      Returns:
      \( U \) corresponding to \( M=U\Sigma V^{H} \) in the SVD.

    • getS

      public Matrix getS()
      Gets the diagonal matrix \( \Sigma \) corresponding to \( M=U\Sigma V^{H} \) in the SVD.
      Returns:
      \( \Sigma \) corresponding to \( M=U\Sigma V^{H} \) in the SVD.

    • getSingularValues

      public Vector getSingularValues()
      Gets the singular values of the last matrix decomposed.
      Returns:
      The singular values of the last matrix decomposed.

    • getV

      public T getV()
      Gets the unitary matrix \( V \) corresponding to \( M=U\Sigma V^{H} \) in the SVD.
      Returns:
      \( V \) corresponding to \( M=U\Sigma V^{H} \) in the SVD. Note that the Hermitian transpose has not been computed.

    • getRank

      public int getRank()
      Gets the rank of the last matrix decomposed. This is computed as a byproduct of the decomposition.
      Returns:
      The rank of the last matrix decomposed.

    • decompose

      public SVD<T> decompose(T src)
      Applies decomposition to the source matrix.
      Specified by:
      decompose in class Decomposition<T extends MatrixMixin<T,?,?,?>>
      Parameters:
      src - The source matrix to decompose.
      Returns:
      A reference to this decomposer.

    • invDirectSum

      protected abstract T invDirectSum(T src)
      Computes the inverse direct sum of a matrix and its Hermitian transpose.
      Parameters:
      src - Matrix to inverse direct add with its Hermitian transpose.
      Returns:
      The inverse direct sum of the src matrix with its Hermitian transpose.

    • computeRank

      protected void computeRank(int rows, int cols, double[] singularValues)
      Computes the rank of the matrix being decomposed using the singular values of the matrix.
      Parameters:
      rows - The number of rows in the original source matrix.
      cols - The number of columns in the original source matrix.
      singularValues - The singular values of the original source matrix.

    • makeEigenPairs

      protected abstract T makeEigenPairs(T B, double[] eigVals)
      Gets the eigen values and vectors of symmetric block matrix which corresponds to the singular values and vectors of the matrix being decomposed.
      Parameters:
      B - Symmetric block matrix to compute the eigenvalues of.
      eigVals - Storage for eigenvalues.
      Returns:
      The eigenvalues and eigenvectors of the symmetric block matrix which corresponds to the singular values and vectors of the matrix being decomposed.

    • makeEigenVals

      protected abstract void makeEigenVals(T B, double[] eigVals)
      Gets the eigen values of the symmetric block matrix which corresponds to the singular values of the matrix being decomposed.
      Parameters:
      B - Symmetric block matrix to compute the eigenvalues of.
      eigVals - Storage for eigenvalues.

    • initUV

      protected abstract void initUV(Shape src, int cols)
      Initializes the unitary \( U \) and \( V \) matrices for the SVD.
      Parameters:
      src - Shape of the source matrix being decomposed.
      cols - The number of columns for \( U \) and \( V \).

    • extractNormalizedCols

      protected abstract void extractNormalizedCols(T singularVecs, int j)
      Extracts the singular vectors, normalizes them and sets the columns of \( U \) and \( V \) to be the left/right singular vectors.
      Parameters:
      singularVecs - Computed left and right singular vectors.
      j - Index of the column of \( U \) and \( V \) to set.