Class UnitaryDecomposition<T extends MatrixMixin<T,?,?,?>,U>

java.lang.Object
org.flag4j.linalg.decompositions.unitary.UnitaryDecomposition<T,U>
Type Parameters:
T - Type of the matrix to be decomposed.
U - Internal storage datatype of the matrix.
All Implemented Interfaces:
Decomposition<T>
Direct Known Subclasses:
ComplexUnitaryDecomposition, RealUnitaryDecomposition

public abstract class UnitaryDecomposition<T extends MatrixMixin<T,?,?,?>,U> extends Object implements Decomposition<T>

This class is the base class for all decompositions which proceed by using unitary transformations (specifically HouseholderOld reflectors) to bring a matrix into an upper triangular matrix (QR decomposition) or an upper Hessenburg matrix (Hessenburg decomposition).

While the QR and Hessenburg decomposition are distinct, they have similar implementations and so this class provides common code for the two decompositions.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    protected boolean
    Flag indicating if a HouseholderOld reflector was needed for the current column meaning the transformMatrix should be updated.
    protected U
    For storing a HouseholderOld vectors.
    protected int
    The minimum of rows and columns in the matrix to be decomposed.
    protected int
    Number of columns in transformMatrix.
    protected int
    Number of rows in transformMatrix.
    protected U
    Storage of the scalar factors for the HouseholderOld reflectors used in the decomposition.
    protected boolean
    Flag indicating if Q should be computed in the decomposition.
    protected final int
    Sub-diagonal of the upper quasi-triangular matrix.
    protected U
    Pointer to the internal data array of transformMatrix.
    protected T
    Storage for the upper triangular/Hessenburg matrix and the vectors of the HouseholderOld reflectors used in the decomposition.
    protected U
    For temporarily storage when applying HouseholderOld vectors.
  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    UnitaryDecomposition(int subDiagonal, boolean storeReflectors)
    Creates a real unitary decomposer which will reduce the matrix to an upper quasi-triangular matrix (Either truly upper or upper Hessenburg).
  • Method Summary

    Modifier and Type
    Method
    Description
    protected abstract void
    Computes the HouseholderOld vector for the first column of the sub-matrix with upper left corner at (j, j).
    protected abstract void
    computePhasedNorm(int j, double maxAbs)
    Computes the norm of column j at and below the jth row of the matrix to be decomposed.
    protected void
    Applies the unitary decomposition to the matrix.
    protected abstract double
    Finds the maximum value in transformMatrix at column j at or below the jth row.
    abstract T
    Gets the unitary Q matrix from the decomposition.
    abstract T
    Gets the upper triangular/Hessenburg matrix from the last decomposition.
    protected abstract T
    Gets the upper triangular/Hessenburg matrix from the last decomposition.
    protected abstract T
    Creates and initializes Q to the appropriately sized identity matrix.
    protected abstract void
    initWorkArrays(int maxAxisSize)
    Initialized any work arrays to be used in computing the decomposition with the proper size.
    protected void
    setUp(T src)
    Initializes storage and other parameters for the decomposition.
    protected abstract void
    updateData(int j)
    Updates the transformMatrix matrix using the computed HouseholderOld vector from computeHouseholder(int).

    Methods inherited from class java.lang.Object

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

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

    decompose
  • Field Details

    • transformMatrix

      protected T extends MatrixMixin<T,?,?,?> transformMatrix

      Storage for the upper triangular/Hessenburg matrix and the vectors of the HouseholderOld reflectors used in the decomposition.

      The upper triangular/Hessenburg will have all zeros below either the diagonal or the first sub-diagonal and will be stored in the top corner above that diagonal. For instance, if the quasi-triangular matrix is truly upper triangular, it will be stored at and above the principle diagonal. If the quasi-triangular matrix is upper Hessenburg, it will be stored at and above the first sub-diagonal.

      The HouseholderOld reflectors used to bring the original matrix to the upper triangular/Hessenburg form will be stored as the columns below the last non-zero sub-diagonal of the quasi-triangular matrix. The first value of each reflector is not stored but is assumed to be 1.

      This provides compact storage for decompositions which proceed by unitary transformations. Further, the full computation of the unitary matrix can be deferred until it is needed.

    • transformData

      protected U transformData
      Pointer to the internal data array of transformMatrix.
    • numRows

      protected int numRows
      Number of rows in transformMatrix.
    • numCols

      protected int numCols
      Number of columns in transformMatrix.
    • qFactors

      protected U qFactors
      Storage of the scalar factors for the HouseholderOld reflectors used in the decomposition.
    • householderVector

      protected U householderVector
      For storing a HouseholderOld vectors.
    • workArray

      protected U workArray
      For temporarily storage when applying HouseholderOld vectors. This is useful for avoiding unneeded garbage collection and for improving cache performance when traversing columns.
    • minAxisSize

      protected int minAxisSize
      The minimum of rows and columns in the matrix to be decomposed.
    • subDiagonal

      protected final int subDiagonal
      Sub-diagonal of the upper quasi-triangular matrix. That is, the sub0diagonal for which all data below will be zero in the final upper quasi-triangular matrix. Must be zero or one. If zero, it will be upper triangular. If one, it will be upper Hessenburg.
    • applyUpdate

      protected boolean applyUpdate
      Flag indicating if a HouseholderOld reflector was needed for the current column meaning the transformMatrix should be updated.
    • storeReflectors

      protected boolean storeReflectors
      Flag indicating if Q should be computed in the decomposition.
  • Constructor Details

    • UnitaryDecomposition

      protected UnitaryDecomposition(int subDiagonal, boolean storeReflectors)
      Creates a real unitary decomposer which will reduce the matrix to an upper quasi-triangular matrix (Either truly upper or upper Hessenburg).
      Parameters:
      subDiagonal - Sub-diagonal of the upper quasi-triangular matrix. Must be zero or one. If zero, it will be upper triangular. If one, it will be upper Hessenburg.
      Throws:
      IllegalArgumentException - If 1 < subDiagonal < 0.
  • Method Details

    • decomposeUnitary

      protected void decomposeUnitary(T src)
      Applies the unitary decomposition to the matrix. Note, the full computation of Q is deferred until getQ() is explicitly called.
      Parameters:
      src - The source matrix to decompose.
    • getQ

      public abstract T getQ()
      Gets the unitary Q matrix from the decomposition. This is the accumulation of all unitary transformation applied to bring the matrix to an upper triangular or Hessenburg form.
      Returns:
      The Q matrix from the decomposition. I.e. the accumulation of all unitary transformation applied during the decomposition.
    • initQ

      protected abstract T initQ()
      Creates and initializes Q to the appropriately sized identity matrix.
      Returns:
      An identity matrix with the appropriate size.
    • getUpper

      protected abstract T getUpper(T U)
      Gets the upper triangular/Hessenburg matrix from the last decomposition.
      Parameters:
      U - Storage for upper triangular/Hessenburg matrix. Assumed to be the zero matrix of an appropriate size.
      Returns:
      The upper triangular/Hessenburg matrix from the last decomposition.
    • getUpper

      public abstract T getUpper()
      Gets the upper triangular/Hessenburg matrix from the last decomposition.
      Returns:
      The upper triangular/Hessenburg matrix from the last decomposition.
    • setUp

      protected void setUp(T src)
      Initializes storage and other parameters for the decomposition.
      Parameters:
      src - Source matrix to be decomposed.
    • initWorkArrays

      protected abstract void initWorkArrays(int maxAxisSize)
      Initialized any work arrays to be used in computing the decomposition with the proper size.
      Parameters:
      maxAxisSize - Length of the largest axis in the matrix to be decomposed. That is, max(numRows, numCols)
    • computeHouseholder

      protected abstract void computeHouseholder(int j)
      Computes the HouseholderOld vector for the first column of the sub-matrix with upper left corner at (j, j).
      Parameters:
      j - Index of the upper left corner of the sub-matrix for which to compute the HouseholderOld vector for the first column. That is, a HouseholderOld vector will be computed for the portion of column j below row j.
    • updateData

      protected abstract void updateData(int j)
      Updates the transformMatrix matrix using the computed HouseholderOld vector from computeHouseholder(int).
      Parameters:
      j - Index of sub-matrix for which the HouseholderOld reflector was computed for.
    • computePhasedNorm

      protected abstract void computePhasedNorm(int j, double maxAbs)
      Computes the norm of column j at and below the jth row of the matrix to be decomposed. The norm will have the same parity as the first entry in the sub-column.
      Parameters:
      j - Column to compute norm of below the jth row.
      maxAbs - Maximum absolute value in the column. Used for scaling norm to minimize potential overflow issues.
    • findMaxAndInit

      protected abstract double findMaxAndInit(int j)
      Finds the maximum value in transformMatrix at column j at or below the jth row. This method also initializes the first numRows-j data of the storage array householderVector to the data of this column.
      Parameters:
      j - Index of column (and starting row) to compute max of.
      Returns:
      The maximum value in transformMatrix at column j at or below the jth row.