Class ComplexUnitaryDecomposition

java.lang.Object
org.flag4j.linalg.decompositions.Decomposition<CMatrix>
org.flag4j.linalg.decompositions.unitary.UnitaryDecomposition<CMatrix,Complex128[]>
org.flag4j.linalg.decompositions.unitary.ComplexUnitaryDecomposition
Direct Known Subclasses:
ComplexHess, ComplexQR
public abstract class ComplexUnitaryDecomposition extends UnitaryDecomposition<CMatrix,Complex128[]>

The base class for complex matrix decompositions which proceed by using unitary transformations (specifically Householder reflectors) to bring a matrix into an upper triangular/Hessenburg matrix. Specifically, the QR and Hessenburg decompositions.

This class is provided because both the QR and Hessenburg decompositions proceed by very similar computations resulting in a substantial amount of overlap in the implementations of the two decompositions. This class serves to implement these common computations such that implementations of either decompositions may utilize them without the need of reimplementing them.

  • Field Details

    • normRe

      protected double normRe
      To store norms of columns in UnitaryDecomposition.transformMatrix. Will be real.

    • norm

      protected Complex128 norm
      For storing the scaled, phase-adjusted norm. This may be complex.

    • currentFactor

      protected Complex128 currentFactor
      Scalar factor of the currently computed Householder reflector.

  • Constructor Details

    • ComplexUnitaryDecomposition

      public ComplexUnitaryDecomposition(int subDiagonal)
      Creates a real unitary decomposer which will reduce the matrix to an upper triangular/Hessenburg matrix which is has zeros below the specified sub-diagonal.
      Parameters:
      subDiagonal - Sub-diagonal of the upper triangular/Hessenburg matrix. That is, the sub-diagonal for which all data below will be zero in the final upper quasi-triangular matrix. Must be Zero or one.
      • subDiagonal = 0: Matrix will be upper triangular.
      • subDiagonal = 1: Matrix will be upper Hessenburg.
      Throws:
      IllegalArgumentException - If subDiagonal < 0 || subDiagonal > 1.

    • ComplexUnitaryDecomposition

      public ComplexUnitaryDecomposition(int subDiagonal, boolean storeReflectors)
      Creates a real unitary decomposer which will reduce the matrix to an upper triangular/Hessenburg matrix which is has zeros below the specified sub-diagonal.

      Allows for specification if the reflectors used to bring matrix to upper triangular/Hessenburg form to be stored or not.

      If the Q matrix is needed, then storeReflectors must be true. If Q is NOT needed, then not storing the reflectors may improve performance slightly by avoiding unneeded copies.

      It should be noted that if performance is improved, it will be a very slight improvement compared to the total time to compute the decomposition. This is because the computation of Q is only evaluated lazily once getQ() is called, so this will only save on copy ops.

      Parameters:
      subDiagonal - Sub-diagonal of the upper triangular/Hessenburg matrix. That is, the sub-diagonal for which all data below will be zero in the final upper quasi-triangular matrix. Must be Zero or one.
      • subDiagonal = 0: Matrix will be upper triangular.
      • subDiagonal = 1: Matrix will be upper Hessenburg.
      storeReflectors - Flag indicating if the reflectors used to bring the matrix to upper triangular/Hessenburg form should be stored.
      Throws:
      IllegalArgumentException - If subDiagonal < 0 || subDiagonal > 1.

    • ComplexUnitaryDecomposition

      public ComplexUnitaryDecomposition(int subDiagonal, boolean storeReflectors, boolean inPlace)
      Creates a real unitary decomposer which will reduce the matrix to an upper triangular/Hessenburg matrix which is has zeros below the specified sub-diagonal.

      Allows for specification if the reflectors used to bring matrix to upper triangular/Hessenburg form to be stored or not.

      If the Q matrix is needed, then storeReflectors must be true. If Q is NOT needed, then not storing the reflectors may improve performance slightly by avoiding unneeded copies.

      It should be noted that if performance is improved, it will be a very slight improvement compared to the total time to compute the decomposition. This is because the computation of Q is only evaluated lazily once getQ() is called, so this will only save on copy ops.

      Parameters:
      subDiagonal - Sub-diagonal of the upper triangular/Hessenburg matrix. That is, the sub-diagonal for which all data below will be zero in the final upper quasi-triangular matrix. Must be Zero or one.
      • subDiagonal = 0: Matrix will be upper triangular.
      • subDiagonal = 1: Matrix will be upper Hessenburg.
      storeReflectors - Flag indicating if the reflectors used to bring the matrix to upper triangular/Hessenburg form should be stored.
      inPlace - Flag indicating if the decomposition should be done in-place.
      • If true, then the decomposition will be done in place.
      • If false, then the decomposition will be done out-of-place.
      Throws:
      IllegalArgumentException - If subDiagonal < 0 || subDiagonal > 1.

  • Method Details

    • getQ

      public CMatrix getQ()

      Gets the unitary Q matrix from the QR decomposition.

      Note, if the reflectors for this decomposition were not saved, then Q can not be computed and this method will be null.

      Specified by:
      getQ in class UnitaryDecomposition<CMatrix,Complex128[]>
      Returns:
      The Q matrix from the QR decomposition. Note, if the reflectors for this decomposition were not saved, then Q can not be computed and this method will return null.

    • getUpper

      protected CMatrix getUpper(CMatrix H)
      Gets the upper triangular/Hessenburg matrix from the last decomposition.
      Specified by:
      getUpper in class UnitaryDecomposition<CMatrix,Complex128[]>
      Parameters:
      H - 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.

    • initWorkArrays

      protected void initWorkArrays(int maxAxisSize)
      Initialized any work arrays to be used in computing the decomposition with the proper size.
      Specified by:
      initWorkArrays in class UnitaryDecomposition<CMatrix,Complex128[]>
      Parameters:
      maxAxisSize - Length of the largest axis in the matrix to be decomposed. That is, max(numRows, numCols)

    • computeHouseholder

      protected void computeHouseholder(int j)
      Computes the Householder vector for the first column of the sub-matrix with upper left corner at (j, j).
      Specified by:
      computeHouseholder in class UnitaryDecomposition<CMatrix,Complex128[]>
      Parameters:
      j - Index of the upper left corner of the sub-matrix for which to compute the Householder vector for the first column. That is, a Householder vector will be computed for the portion of column j below row j.

    • computePhasedNorm

      protected void computePhasedNorm(int j, double maxAbs)
      Computes the norm of column j 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.
      Specified by:
      computePhasedNorm in class UnitaryDecomposition<CMatrix,Complex128[]>
      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 double findMaxAndInit(int j)
      Finds the maximum value in UnitaryDecomposition.transformMatrix at column j at or below the jth row. This method also initializes the first numRows-j data of the storage array UnitaryDecomposition.householderVector to the data of this column.
      Specified by:
      findMaxAndInit in class UnitaryDecomposition<CMatrix,Complex128[]>
      Parameters:
      j - Index of column (and starting row) to compute max of.
      Returns:
      The maximum value in UnitaryDecomposition.transformMatrix at column j at or below the jth row.

    • updateData

      protected void updateData(int j)
      Updates the UnitaryDecomposition.transformMatrix matrix using the computed Householder vector from computeHouseholder(int).
      Specified by:
      updateData in class UnitaryDecomposition<CMatrix,Complex128[]>
      Parameters:
      j - Index of sub-matrix for which the Householder reflector was computed for.