complex16OTHERcomputational(3)

📦

version 3.11.0 · 2 versions

3.11.0 · debian bookworm (latest)
3.10.0 · ubuntu jammy

💖 complex16OTHERcomputational — LAPACK, section 3 💖

okay bestie, so you found yourself a LAPACK man page and it's the complex16OTHERcomputational one, from the LAPACK manual, section 3. this is giving "we're about to do some serious linear algebra and we're doing it in style" energy and honestly? obsessed already. 🦋

✨ NAME ✨

complex16OTHERcomputational — complex16 🌸

heads up bestie: this page is LONG, like 57-parts long, and this is only part 1. more is coming, so don't go anywhere. 💅

ok bestie we're continuing the function rollout, no re-intros, just vibes and subroutine signatures 💖 every single one is here, nothing skipped, no cap:

subroutine zbbcsd (JOBU1, JOBU2, JOBV1T, JOBV2T, TRANS, M, P, Q, THETA, PHI, U1, LDU1, U2, LDU2, V1T, LDV1T, V2T, LDV2T, B11D, B11E, B12D, B12E, B21D, B21E, B22D, B22E, RWORK, LRWORK, INFO) — ZBBCSD
subroutine zbdsqr (UPLO, N, NCVT, NRU, NCC, D, E, VT, LDVT, U, LDU, C, LDC, RWORK, INFO) — ZBDSQR
subroutine zgghd3 (COMPQ, COMPZ, N, ILO, IHI, A, LDA, B, LDB, Q, LDQ, Z, LDZ, WORK, LWORK, INFO) — ZGGHD3
subroutine zgghrd (COMPQ, COMPZ, N, ILO, IHI, A, LDA, B, LDB, Q, LDQ, Z, LDZ, INFO) — ZGGHRD
subroutine zggqrf (N, M, P, A, LDA, TAUA, B, LDB, TAUB, WORK, LWORK, INFO) — ZGGQRF
subroutine zggrqf (M, P, N, A, LDA, TAUA, B, LDB, TAUB, WORK, LWORK, INFO) — ZGGRQF
subroutine zggsvp3 (JOBU, JOBV, JOBQ, M, P, N, A, LDA, B, LDB, TOLA, TOLB, K, L, U, LDU, V, LDV, Q, LDQ, IWORK, RWORK, TAU, WORK, LWORK, INFO) — ZGGSVP3
subroutine zgsvj0 (JOBV, M, N, A, LDA, D, SVA, MV, V, LDV, EPS, SFMIN, TOL, NSWEEP, WORK, LWORK, INFO) — ZGSVJ0 pre-processor for the routine zgesvj.
subroutine zgsvj1 (JOBV, M, N, N1, A, LDA, D, SVA, MV, V, LDV, EPS, SFMIN, TOL, NSWEEP, WORK, LWORK, INFO) — ZGSVJ1 pre-processor for the routine zgesvj, applies Jacobi rotations targeting only particular pivots.
subroutine zhbgst (VECT, UPLO, N, KA, KB, AB, LDAB, BB, LDBB, X, LDX, WORK, RWORK, INFO) — ZHBGST
subroutine zhbtrd (VECT, UPLO, N, KD, AB, LDAB, D, E, Q, LDQ, WORK, INFO) — ZHBTRD
subroutine zhetrd_hb2st (STAGE1, VECT, UPLO, N, KD, AB, LDAB, D, E, HOUS, LHOUS, WORK, LWORK, INFO) — ZHETRD_HB2ST reduces a complex Hermitian band matrix A to real symmetric tridiagonal form T
subroutine zhfrk (TRANSR, UPLO, TRANS, N, K, ALPHA, A, LDA, BETA, C) — ZHFRK performs a Hermitian rank-k operation for matrix in RFP format.
subroutine zhpcon (UPLO, N, AP, IPIV, ANORM, RCOND, WORK, INFO) — ZHPCON
subroutine zhpgst (ITYPE, UPLO, N, AP, BP, INFO) — ZHPGST
subroutine zhprfs (UPLO, N, NRHS, AP, AFP, IPIV, B, LDB, X, LDX, FERR, BERR, WORK, RWORK, INFO) — ZHPRFS
subroutine zhptrd (UPLO, N, AP, D, E, TAU, INFO) — ZHPTRD
subroutine zhptrf (UPLO, N, AP, IPIV, INFO) — ZHPTRF
subroutine zhptri (UPLO, N, AP, IPIV, WORK, INFO) — ZHPTRI
subroutine zhptrs (UPLO, N, NRHS, AP, IPIV, B, LDB, INFO) — ZHPTRS
subroutine zhsein (SIDE, EIGSRC, INITV, SELECT, N, H, LDH, W, VL, LDVL, VR, LDVR, MM, M, WORK, RWORK, IFAILL, IFAILR, INFO) — ZHSEIN
subroutine zhseqr (JOB, COMPZ, N, ILO, IHI, H, LDH, W, Z, LDZ, WORK, LWORK, INFO) — ZHSEQR
subroutine zla_lin_berr (N, NZ, NRHS, RES, AYB, BERR) — ZLA_LIN_BERR computes a component-wise relative backward error.
subroutine zla_wwaddw (N, X, Y, W) — ZLA_WWADDW adds a vector into a doubled-single vector.
subroutine zlaed0 (QSIZ, N, D, E, Q, LDQ, QSTORE, LDQS, RWORK, IWORK, INFO) — ZLAED0 used by ZSTEDC. Computes all eigenvalues and corresponding eigenvectors of an unreduced symmetric tridiagonal matrix using the divide and conquer method.
subroutine zlaed7 (N, CUTPNT, QSIZ, TLVLS, CURLVL, CURPBM, D, Q, LDQ, RHO, INDXQ, QSTORE, QPTR, PRMPTR, PERM, GIVPTR, GIVCOL, GIVNUM, WORK, RWORK, IWORK, INFO) — ZLAED7 used by ZSTEDC. Computes the updated eigensystem of a diagonal matrix after modification by a rank-one symmetric matrix. Used when the original matrix is dense.
subroutine zlaed8 (K, N, QSIZ, Q, LDQ, D, RHO, CUTPNT, Z, DLAMDA, Q2, LDQ2, W, INDXP, INDX, INDXQ, PERM, GIVPTR, GIVCOL, GIVNUM, INFO) — ZLAED8 used by ZSTEDC. Merges eigenvalues and deflates secular equation. Used when the original matrix is dense.
subroutine zlals0 (ICOMPQ, NL, NR, SQRE, NRHS, B, LDB, BX, LDBX, PERM, GIVPTR, GIVCOL, LDGCOL, GIVNUM, LDGNUM, POLES, DIFL, DIFR, Z, K, C, S, RWORK, INFO) — ZLALS0 applies back multiplying factors in solving the least squares problem using divide and conquer SVD approach. Used by sgelsd.
subroutine zlalsa (ICOMPQ, SMLSIZ, N, NRHS, B, LDB, BX, LDBX, U, LDU, VT, K, DIFL, DIFR, Z, POLES, GIVPTR, GIVCOL, LDGCOL, PERM, GIVNUM, C, S, RWORK, IWORK, INFO) — ZLALSA computes the SVD of the coefficient matrix in compact form. Used by sgelsd.
subroutine zlalsd (UPLO, SMLSIZ, N, NRHS, D, E, B, LDB, RCOND, RANK, WORK, RWORK, IWORK, INFO) — ZLALSD uses the singular value decomposition of A to solve the least squares problem.
double precision function zlanhf (NORM, TRANSR, UPLO, N, A, WORK) — ZLANHF returns the value of the 1-norm, or the Frobenius norm, or the infinity norm, or the element of largest absolute value of a Hermitian matrix in RFP format.
subroutine zlarscl2 (M, N, D, X, LDX) — ZLARSCL2 performs reciprocal diagonal scaling on a matrix.
subroutine zlarz (SIDE, M, N, L, V, INCV, TAU, C, LDC, WORK) — ZLARZ applies an elementary reflector (as returned by stzrzf) to a general matrix.
subroutine zlarzb (SIDE, TRANS, DIRECT, STOREV, M, N, K, L, V, LDV, T, LDT, C, LDC, WORK, LDWORK) — ZLARZB applies a block reflector or its conjugate-transpose to a general matrix.
subroutine zlarzt (DIRECT, STOREV, N, K, V, LDV, TAU, T, LDT) — ZLARZT forms the triangular factor T of a block reflector H = I - vtvH.
subroutine zlascl2 (M, N, D, X, LDX) — ZLASCL2 performs diagonal scaling on a matrix.
subroutine zlatrz (M, N, L, A, LDA, TAU, WORK) — ZLATRZ factors an upper trapezoidal matrix by means of unitary transformations.
subroutine zpbcon (UPLO, N, KD, AB, LDAB, ANORM, RCOND, WORK, RWORK, INFO) — ZPBCON
subroutine zpbequ (UPLO, N, KD, AB, LDAB, S, SCOND, AMAX, INFO) — ZPBEQU
subroutine zpbrfs (UPLO, N, KD, NRHS, AB, LDAB, AFB, LDAFB, B, LDB, X, LDX, FERR, BERR, WORK, RWORK, INFO) — ZPBRFS
subroutine zpbstf (UPLO, N, KD, AB, LDAB, INFO) — ZPBSTF
subroutine zpbtf2 (UPLO, N, KD, AB, LDAB, INFO) — ZPBTF2 computes the Cholesky factorization of a symmetric/Hermitian positive definite band matrix (unblocked algorithm).
subroutine zpbtrf (UPLO, N, KD, AB, LDAB, INFO) — ZPBTRF
subroutine zpbtrs (UPLO, N, KD, NRHS, AB, LDAB, B, LDB, INFO) — ZPBTRS
subroutine zpftrf (TRANSR, UPLO, N, A, INFO) — ZPFTRF
subroutine zpftri (TRANSR, UPLO, N, A, INFO) — ZPFTRI
subroutine zpftrs (TRANSR, UPLO, N, NRHS, A, B, LDB, INFO) — ZPFTRS
subroutine zppcon (UPLO, N, AP, ANORM, RCOND, WORK, RWORK, INFO) — ZPPCON
subroutine zppequ (UPLO, N, AP, S, SCOND, AMAX, INFO) — ZPPEQU
subroutine zpprfs (UPLO, N, NRHS, AP, AFP, B, LDB, X, LDX, FERR, BERR, WORK, RWORK, INFO) — ZPPRFS
subroutine zpptrf (UPLO, N, AP, INFO) — ZPPTRF
subroutine zpptri (UPLO, N, AP, INFO) — ZPPTRI
subroutine zpptrs (UPLO, N, NRHS, AP, B, LDB, INFO) — ZPPTRS
subroutine zpstf2 (UPLO, N, A, LDA, PIV, RANK, TOL, WORK, INFO) — ZPSTF2 computes the Cholesky factorization with complete pivoting of a complex Hermitian positive semidefinite matrix.
subroutine zpstrf (UPLO, N, A, LDA, PIV, RANK, TOL, WORK, INFO) — ZPSTRF computes the Cholesky factorization with complete pivoting of a complex Hermitian positive semidefinite matrix.
subroutine zspcon (UPLO, N, AP, IPIV, ANORM, RCOND, WORK, INFO) — ZSPCON
subroutine zsprfs (UPLO, N, NRHS, AP, AFP, IPIV, B, LDB, X, LDX, FERR, BERR, WORK, RWORK, INFO) — ZSPRFS
subroutine zsptrf (UPLO, N, AP, IPIV, INFO) — ZSPTRF
subroutine zsptri (UPLO, N, AP, IPIV, WORK, INFO) — ZSPTRI
subroutine zsptrs (UPLO, N, NRHS, AP, IPIV, B, LDB, INFO) — ZSPTRS
subroutine zstedc (COMPZ, N, D, E, Z, LDZ, WORK, LWORK, RWORK, LRWORK, IWORK, LIWORK, INFO) — ZSTEDC
subroutine zstegr (JOBZ, RANGE, N, D, E, VL, VU, IL, IU, ABSTOL, M, W, Z, LDZ, ISUPPZ, WORK, LWORK, IWORK, LIWORK, INFO) — ZSTEGR
subroutine zstein (N, D, E, M, W, IBLOCK, ISPLIT, Z, LDZ, WORK, IWORK, IFAIL, INFO) — ZSTEIN
subroutine zstemr (JOBZ, RANGE, N, D, E, VL, VU, IL, IU, M, W, Z, LDZ, NZC, ISUPPZ, TRYRAC, WORK, LWORK, IWORK, LIWORK, INFO) — ZSTEMR
subroutine zsteqr (COMPZ, N, D, E, Z, LDZ, WORK, INFO) — ZSTEQR
subroutine ztbcon (NORM, UPLO, DIAG, N, KD, AB, LDAB, RCOND, WORK, RWORK, INFO) — ZTBCON
subroutine ztbrfs (UPLO, TRANS, DIAG, N, KD, NRHS, AB, LDAB, B, LDB, X, LDX, FERR, BERR, WORK, RWORK, INFO) — ZTBRFS
subroutine ztbtrs (UPLO, TRANS, DIAG, N, KD, NRHS, AB, LDAB, B, LDB, INFO) — ZTBTRS
subroutine ztfsm (TRANSR, SIDE, UPLO, TRANS, DIAG, M, N, ALPHA, A, B, LDB) — ZTFSM solves a matrix equation (one operand is a triangular matrix in RFP format).
subroutine ztftri (TRANSR, UPLO, DIAG, N, A, INFO) — ZTFTRI
subroutine ztfttp (TRANSR, UPLO, N, ARF, AP, INFO) — ZTFTTP copies a triangular matrix from the rectangular full packed format (TF) to the standard packed format (TP).
subroutine ztfttr (TRANSR, UPLO, N, ARF, A, LDA, INFO) — ZTFTTR copies a triangular matrix from the rectangular full packed format (TF) to the standard full format (TR).
subroutine ztgsen (IJOB, WANTQ, WANTZ, SELECT, N, A, LDA, B, LDB, ALPHA, BETA, Q, LDQ, Z, LDZ, M, PL, PR, DIF, WORK, LWORK, IWORK, LIWORK, INFO) — ZTGSEN
subroutine ztgsja (JOBU, JOBV, JOBQ, M, P, N, K, L, A, LDA, B, LDB, TOLA, TOLB, ALPHA, BETA, U, LDU, V, LDV, Q, LDQ, WORK, NCYCLE, INFO) — ZTGSJA
subroutine ztgsna (JOB, HOWMNY, SELECT, N, A, LDA, B, LDB, VL, LDVL, VR, LDVR, S, DIF, MM, M, WORK, LWORK, IWORK, INFO) — ZTGSNA
subroutine ztpcon (NORM, UPLO, DIAG, N, AP, RCOND, WORK, RWORK, INFO) — ZTPCON
subroutine ztpmqrt (SIDE, TRANS, M, N, K, L, NB, V, LDV, T, LDT, A, LDA, B, LDB, WORK, INFO) — ZTPMQRT
subroutine ztpqrt (M, N, L, NB, A, LDA, B, LDB, T, LDT, WORK, INFO) — ZTPQRT
subroutine ztpqrt2 (M, N, L, A, LDA, B, LDB, T, LDT, INFO) — ZTPQRT2 computes a QR factorization of a real or complex 'triangular-pentagonal' matrix, which is composed of a triangular block and a pentagonal block, using the compact WY representation for Q.
subroutine ztprfs (UPLO, TRANS, DIAG, N, NRHS, AP, B, LDB, X, LDX, FERR, BERR, WORK, RWORK, INFO) — ZTPRFS
subroutine ztptri (UPLO, DIAG, N, AP, INFO) — ZTPTRI
subroutine ztptrs (UPLO, TRANS, DIAG, N, NRHS, AP, B, LDB, INFO) — ZTPTRS
subroutine ztpttf (TRANSR, UPLO, N, AP, ARF, INFO) — ZTPTTF copies a triangular matrix from the standard packed format (TP) to the rectangular full packed format (TF).
subroutine ztpttr (UPLO, N, AP, A, LDA, INFO)
ZTPTTR — copies a triangular matrix from the standard packed format (TP) to the standard full format (TR). ✨
subroutine ztrcon (NORM, UPLO, DIAG, N, A, LDA, RCOND, WORK, RWORK, INFO) — ZTRCON
subroutine ztrevc (SIDE, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR, MM, M, WORK, RWORK, INFO) — ZTREVC
subroutine ztrevc3 (SIDE, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR, MM, M, WORK, LWORK, RWORK, LRWORK, INFO) — ZTREVC3
subroutine ztrexc (COMPQ, N, T, LDT, Q, LDQ, IFST, ILST, INFO) — ZTREXC
subroutine ztrrfs (UPLO, TRANS, DIAG, N, NRHS, A, LDA, B, LDB, X, LDX, FERR, BERR, WORK, RWORK, INFO) — ZTRRFS
subroutine ztrsen (JOB, COMPQ, SELECT, N, T, LDT, Q, LDQ, W, M, S, SEP, WORK, LWORK, INFO) — ZTRSEN
subroutine ztrsna (JOB, HOWMNY, SELECT, N, T, LDT, VL, LDVL, VR, LDVR, S, SEP, MM, M, WORK, LDWORK, RWORK, INFO) — ZTRSNA
subroutine ztrti2 (UPLO, DIAG, N, A, LDA, INFO) — ZTRTI2 computes the inverse of a triangular matrix (unblocked algorithm). unblocked, bestie, so you know what that means 💅
subroutine ztrtri (UPLO, DIAG, N, A, LDA, INFO) — ZTRTRI
subroutine ztrtrs (UPLO, TRANS, DIAG, N, NRHS, A, LDA, B, LDB, INFO) — ZTRTRS
subroutine ztrttf (TRANSR, UPLO, N, A, LDA, ARF, INFO) — ZTRTTF copies a triangular matrix from the standard full format (TR) to the rectangular full packed format (TF). 🎀
subroutine ztrttp (UPLO, N, A, LDA, AP, INFO) — ZTRTTP copies a triangular matrix from the standard full format (TR) to the standard packed format (TP). 🎀
subroutine ztzrzf (M, N, A, LDA, TAU, WORK, LWORK, INFO) — ZTZRZF
subroutine zunbdb (TRANS, SIGNS, M, P, Q, X11, LDX11, X12, LDX12, X21, LDX21, X22, LDX22, THETA, PHI, TAUP1, TAUP2, TAUQ1, TAUQ2, WORK, LWORK, INFO) — ZUNBDB
subroutine zunbdb1 (M, P, Q, X11, LDX11, X21, LDX21, THETA, PHI, TAUP1, TAUP2, TAUQ1, WORK, LWORK, INFO) — ZUNBDB1
subroutine zunbdb2 (M, P, Q, X11, LDX11, X21, LDX21, THETA, PHI, TAUP1, TAUP2, TAUQ1, WORK, LWORK, INFO) — ZUNBDB2
subroutine zunbdb3 (M, P, Q, X11, LDX11, X21, LDX21, THETA, PHI, TAUP1, TAUP2, TAUQ1, WORK, LWORK, INFO) — ZUNBDB3
subroutine zunbdb4 (M, P, Q, X11, LDX11, X21, LDX21, THETA, PHI, TAUP1, TAUP2, TAUQ1, PHANTOM, WORK, LWORK, INFO) — ZUNBDB4 (yes bestie, there is literally a parameter called PHANTOM, and no I will not be normal about it 👻)
subroutine zunbdb5 (M1, M2, N, X1, INCX1, X2, INCX2, Q1, LDQ1, Q2, LDQ2, WORK, LWORK, INFO) — ZUNBDB5
subroutine zunbdb6 (M1, M2, N, X1, INCX1, X2, INCX2, Q1, LDQ1, Q2, LDQ2, WORK, LWORK, INFO) — ZUNBDB6
recursive subroutine zuncsd (JOBU1, JOBU2, JOBV1T, JOBV2T, TRANS, SIGNS, M, P, Q, X11, LDX11, X12, LDX12, X21, LDX21, X22, LDX22, THETA, U1, LDU1, U2, LDU2, V1T, LDV1T, V2T, LDV2T, WORK, LWORK, RWORK, LRWORK, IWORK, INFO) — ZUNCSD (recursive, iconic, no notes ✨)
subroutine zuncsd2by1 (JOBU1, JOBU2, JOBV1T, M, P, Q, X11, LDX11, X21, LDX21, THETA, U1, LDU1, U2, LDU2, V1T, LDV1T, WORK, LWORK, RWORK, LRWORK, IWORK, INFO) — ZUNCSD2BY1
subroutine zung2l (M, N, K, A, LDA, TAU, WORK, INFO) — ZUNG2L generates all or part of the unitary matrix Q from a QL factorization determined by cgeqlf (unblocked algorithm).
subroutine zung2r (M, N, K, A, LDA, TAU, WORK, INFO) — ZUNG2R
subroutine zunghr (N, ILO, IHI, A, LDA, TAU, WORK, LWORK, INFO) — ZUNGHR
subroutine zungl2 (M, N, K, A, LDA, TAU, WORK, INFO) — ZUNGL2 generates all or part of the unitary matrix Q from an LQ factorization determined by cgelqf (unblocked algorithm).
subroutine zunglq (M, N, K, A, LDA, TAU, WORK, LWORK, INFO) — ZUNGLQ
subroutine zungql (M, N, K, A, LDA, TAU, WORK, LWORK, INFO) — ZUNGQL
subroutine zungqr (M, N, K, A, LDA, TAU, WORK, LWORK, INFO) — ZUNGQR
subroutine zungr2 (M, N, K, A, LDA, TAU, WORK, INFO) — ZUNGR2 generates all or part of the unitary matrix Q from an RQ factorization determined by cgerqf (unblocked algorithm).
subroutine zungrq (M, N, K, A, LDA, TAU, WORK, LWORK, INFO) — ZUNGRQ
subroutine zungtr (UPLO, N, A, LDA, TAU, WORK, LWORK, INFO) — ZUNGTR
subroutine zungtsqr (M, N, MB, NB, A, LDA, T, LDT, WORK, LWORK, INFO) — ZUNGTSQR
subroutine zungtsqr_row (M, N, MB, NB, A, LDA, T, LDT, WORK, LWORK, INFO) — ZUNGTSQR_ROW
subroutine zunhr_col (M, N, NB, A, LDA, T, LDT, D, INFO) — ZUNHR_COL
subroutine zunm2l (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, INFO) — ZUNM2L multiplies a general matrix by the unitary matrix from a QL factorization determined by cgeqlf (unblocked algorithm).
subroutine zunm2r (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, INFO) — ZUNM2R multiplies a general matrix by the unitary matrix from a QR factorization determined by cgeqrf (unblocked algorithm).
subroutine zunmbr (VECT, SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — ZUNMBR
subroutine zunmhr (SIDE, TRANS, M, N, ILO, IHI, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — ZUNMHR
subroutine zunml2 (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, INFO) — ZUNML2 multiplies a general matrix by the unitary matrix from a LQ factorization determined by cgelqf (unblocked algorithm).
subroutine zunmlq (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — ZUNMLQ
subroutine zunmql (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — ZUNMQL
subroutine zunmqr (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — ZUNMQR
subroutine zunmr2 (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, INFO) — ZUNMR2 multiplies a general matrix by the unitary matrix from a RQ factorization determined by cgerqf (unblocked algorithm).
subroutine zunmr3 (SIDE, TRANS, M, N, K, L, A, LDA, TAU, C, LDC, WORK, INFO) — ZUNMR3 multiplies a general matrix by the unitary matrix from a RZ factorization determined by ctzrzf (unblocked algorithm).
subroutine zunmrq (SIDE, TRANS, M, N, K, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — ZUNMRQ
subroutine zunmrz (SIDE, TRANS, M, N, K, L, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — ZUNMRZ
subroutine zunmtr (SIDE, UPLO, TRANS, M, N, A, LDA, TAU, C, LDC, WORK, LWORK, INFO) — ZUNMTR
subroutine zupgtr (UPLO, N, AP, TAU, Q, LDQ, WORK, INFO) — ZUPGTR
subroutine zupmtr (SIDE, UPLO, TRANS, M, N, AP, TAU, C, LDC, WORK, INFO) — ZUPMTR

💖 Detailed Description 💖

This is the group of complex16 other Computational routines. That's it, that's the whole vibe check. 🫶

✨ Function Documentation ✨

🦋 subroutine zbbcsd (character JOBU1, character JOBU2, character JOBV1T, character JOBV2T, character TRANS, integer M, integer P, integer Q, double precision, dimension( * ) THETA, double precision, dimension( * ) PHI, complex16, dimension( ldu1, ) U1, integer LDU1, complex16, dimension( ldu2, ) U2, integer LDU2, complex16, dimension( ldv1t, ) V1T, integer LDV1T, complex16, dimension( ldv2t, ) V2T, integer LDV2T, double precision, dimension( * ) B11D, double precision, dimension( * ) B11E, double precision, dimension( * ) B12D, double precision, dimension( * ) B12E, double precision, dimension( * ) B21D, double precision, dimension( * ) B21E, double precision, dimension( * ) B22D, double precision, dimension( * ) B22E, double precision, dimension( * ) RWORK, integer LRWORK, integer INFO) 🦋

`ZBBCSD`

🌸 Purpose 🌸

ZBBCSD computes the CS decomposition of a unitary matrix in bidiagonal-block form,

    [ B11 | B12 0  0 ]
    [  0  |  0 -I  0 ]
X = [----------------]
    [ B21 | B22 0  0 ]
    [  0  |  0  0  I ]

                              [  C | -S  0  0 ]
                  [ U1 |    ] [  0 |  0 -I  0 ] [ V1 |    ]**H
                = [---------] [---------------] [---------]   .
                  [    | U2 ] [  S |  C  0  0 ] [    | V2 ]
                              [  0 |  0  0  I ]

X is M-by-M, its top-left block is P-by-Q, and Q must be no larger than P, M-P, or M-Q. (If Q is not the smallest index, then X must be transposed and/or permuted. This can be done in constant time using the TRANS and SIGNS options. See ZUNCSD for details.) 😌

The bidiagonal matrices B11, B12, B21, and B22 are represented implicitly by angles THETA(1:Q) and PHI(1:Q-1). 🎀

The unitary matrices U1, U2, V1T, and V2T are input/output. The input matrices are pre- or post-multiplied by the appropriate singular vector matrices. 💫

🧚 Parameters 🧚

JOBU1 — is CHARACTER
- = 'Y': U1 is updated;
- otherwise: U1 is not updated.
JOBU2 — is CHARACTER
- = 'Y': U2 is updated;
- otherwise: U2 is not updated.
JOBV1T — is CHARACTER
- = 'Y': V1T is updated;
- otherwise: V1T is not updated.
JOBV2T — is CHARACTER
- = 'Y': V2T is updated;
- otherwise: V2T is not updated.
TRANS — is CHARACTER
- = 'T': X, U1, U2, V1T, and V2T are stored in row-major order;
- otherwise: X, U1, U2, V1T, and V2T are stored in column-major order.
M — is INTEGER
- The number of rows and columns in X, the unitary matrix in bidiagonal-block form.
P — is INTEGER
- The number of rows in the top-left block of X. 0 <= P <= M.
Q — is INTEGER
- The number of columns in the top-left block of X. 0 <= Q <= MIN(P,M-P,M-Q).
THETA — is DOUBLE PRECISION array, dimension (Q)
- On entry, the angles THETA(1),...,THETA(Q) that, along with PHI(1), ...,PHI(Q-1), define the matrix in bidiagonal-block form. On exit, the angles whose cosines and sines define the diagonal blocks in the CS decomposition.
PHI — is DOUBLE PRECISION array, dimension (Q-1)
- The angles PHI(1),...,PHI(Q-1) that, along with THETA(1),..., THETA(Q), define the matrix in bidiagonal-block form.
U1 — is COMPLEX*16 array, dimension (LDU1,P)
- On entry, a P-by-P matrix. On exit, U1 is postmultiplied by the left singular vector matrix common to [ B11 ; 0 ] and [ B12 0 0 ; 0 -I 0 0 ].
LDU1 — is INTEGER
- The leading dimension of the array U1, LDU1 >= MAX(1,P).
U2
U2 — COMPLEX*16 array, dimension (LDU2,M-P)

On entry, an (M-P)-by-(M-P) matrix. On exit, U2 gets postmultiplied by the left singular vector matrix common to [ B21 ; 0 ] and [ B22 0 0 ; 0 0 I ]. 💫

LDU2 — INTEGER

The leading dimension of the array U2, and bestie, LDU2 >= MAX(1,M-P). No exceptions, the compiler will simply Not Have It otherwise. 🙅‍♀️

V1T — COMPLEX*16 array, dimension (LDV1T,Q)

On entry, a Q-by-Q matrix. On exit, V1T gets premultiplied by the conjugate transpose of the right singular vector matrix common to [ B11 ; 0 ] and [ B21 ; 0 ]. the way it just... conjugates and transposes?? iconic behavior honestly ✨

LDV1T — INTEGER

The leading dimension of the array V1T, LDV1T >= MAX(1,Q). periodt.

V2T — COMPLEX*16 array, dimension (LDV2T,M-Q)

On entry, an (M-Q)-by-(M-Q) matrix. On exit, V2T is premultiplied by the conjugate transpose of the right singular vector matrix common to [ B12 0 0 ; 0 -I 0 ] and [ B22 0 0 ; 0 0 I ]. yes there's a minus sign in there, she's different, we love her 💅

LDV2T — INTEGER

The leading dimension of the array V2T, LDV2T >= MAX(1,M-Q).

B11D — DOUBLE PRECISION array, dimension (Q)

When ZBBCSD converges, B11D contains the cosines of THETA(1), ..., THETA(Q). If ZBBCSD fails to converge, then B11D contains the diagonal of the partially reduced top-left block. two moods, one array 🎀

B11E — DOUBLE PRECISION array, dimension (Q-1)

When ZBBCSD converges, B11E contains zeros. If ZBBCSD fails to converge, then B11E contains the superdiagonal of the partially reduced top-left block.

B12D — DOUBLE PRECISION array, dimension (Q)

When ZBBCSD converges, B12D contains the negative sines of THETA(1), ..., THETA(Q). If ZBBCSD fails to converge, then B12D contains the diagonal of the partially reduced top-right block. negative sines!! she's going through something 💀

B12E — DOUBLE PRECISION array, dimension (Q-1)

When ZBBCSD converges, B12E contains zeros. If ZBBCSD fails to converge, then B12E contains the subdiagonal of the partially reduced top-right block. (note: sub, not super, don't mix them up bestie 😭)

B21D — DOUBLE PRECISION array, dimension (Q)

When ZBBCSD converges, B21D contains the negative sines of THETA(1), ..., THETA(Q). If ZBBCSD fails to converge, then B21D contains the diagonal of the partially reduced bottom-left block.

B21E — DOUBLE PRECISION array, dimension (Q-1)

When ZBBCSD converges, B21E contains zeros. If ZBBCSD fails to converge, then B21E contains the subdiagonal of the partially reduced bottom-left block.

B22D — DOUBLE PRECISION array, dimension (Q)

When ZBBCSD converges, B22D contains the negative sines of THETA(1), ..., THETA(Q). If ZBBCSD fails to converge, then B22D contains the diagonal of the partially reduced bottom-right block.

B22E — DOUBLE PRECISION array, dimension (Q-1)

When ZBBCSD converges, B22E contains zeros. If ZBBCSD fails to converge, then B22E contains the subdiagonal of the partially reduced bottom-right block. ok that's the last of the B's, we made it 🫶

RWORK — DOUBLE PRECISION array, dimension (MAX(1,LRWORK))

On exit, if INFO = 0, RWORK(1) returns the optimal LRWORK. she's telling you what she needs, listen to her 🦋

LRWORK — INTEGER

The dimension of the array RWORK. LRWORK >= MAX(1,8*Q).

If LRWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the RWORK array, returns this value as the first entry of the work array, and no error message related to LRWORK is issued by XERBLA. classic "-1 means I'm just vibing and asking questions" move 💅

INFO — INTEGER
- = 0: successful exit. slay 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. someone passed a bad argument and now we're all paying for it 😭
- > 0: if ZBBCSD did not converge, INFO specifies the number of nonzero entries in PHI, and B11D, B11E, etc., contain the partially reduced matrix. not a vibe but at least she tells you what happened 🫠

✨ Internal Parameters ✨

TOLMUL — DOUBLE PRECISION, default = MAX(10,MIN(100,EPS**(-1/8)))

TOLMUL controls the convergence criterion of the QR loop. Angles THETA(i), PHI(i) are rounded to 0 or PI/2 when they are within TOLMUL*EPS of either bound. basically if it's close enough to the edge we just... call it the edge. manifesting 🧚

✨ References ✨

Brian D. Sutton. Computing the complete CS decomposition. Numer. Algorithms, 50(1):33-65, 2009. (yes we cite, we're academic AND cute 💜)

✨ Author ✨

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

the whole squad showed up for this one 🌈

✨ subroutine zbdsqr (character UPLO, integer N, integer NCVT, integer NRU, integer NCC, double precision, dimension( * ) D, double precision, dimension( * ) E, complex16, dimension( ldvt, ) VT, integer LDVT, complex16, dimension( ldu, ) U, integer LDU, complex16, dimension( ldc, ) C, integer LDC, double precision, dimension( * ) RWORK, integer INFO) ✨

ZBDSQR

✨ Purpose ✨

ZBDSQR computes the singular values and, optionally, the right and/or left singular vectors from the singular value decomposition (SVD) of a real N-by-N (upper or lower) bidiagonal matrix B using the implicit zero-shift QR algorithm. The SVD of B has the form

   B = Q * S * P**H

where S is the diagonal matrix of singular values, Q is an orthogonal matrix of left singular vectors, and P is an orthogonal matrix of right singular vectors. If left singular vectors are requested, this subroutine actually returns U*Q instead of Q, and, if right singular vectors are requested, this subroutine returns P**H*VT instead of P**H, for given complex input matrices U and VT. When U and VT are the unitary matrices that reduce a general matrix A to bidiagonal form: A = U*B*VT, as computed by ZGEBRD, then

   A = (U*Q) * S * (P**H*VT)

is the SVD of A. Optionally, the subroutine may also compute Q**H*C for a given complex input matrix C. ok so she's doing the whole glow-up transformation pipeline, no cap 👑

See 'Computing Small Singular Values of Bidiagonal Matrices With Guaranteed High Relative Accuracy,' by J. Demmel and W. Kahan, LAPACK Working Note #3 (or SIAM J. Sci. Statist. Comput. vol. 11, no. 5, pp. 873-912, Sept 1990) and 'Accurate singular values and differential qd algorithms,' by B. Parlett and V. Fernando, Technical Report CPAM-554, Mathematics Department, University of California at Berkeley, July 1992 for a detailed description of the algorithm. the receipts are RIGHT THERE bestie, read them 📚

✨ Parameters ✨

UPLO — CHARACTER*1
- = 'U': B is upper bidiagonal;
- = 'L': B is lower bidiagonal.

pick your fighter 🎀

N — INTEGER

The order of the matrix B. N >= 0.

NCVT — INTEGER

The number of columns of the matrix VT. NCVT >= 0.

NRU — INTEGER

The number of rows of the matrix U. NRU >= 0.

NCC — INTEGER

The number of columns of the matrix C. NCC >= 0.

D — DOUBLE PRECISION array, dimension (N)

On entry, the n diagonal elements of the bidiagonal matrix B. On exit, if INFO=0, the singular values of B in decreasing order. glow-up complete ✨

E — DOUBLE PRECISION array, dimension (N-1)

On entry, the N-1 offdiagonal elements of the bidiagonal matrix B. On exit, if INFO = 0, E is destroyed; if INFO > 0, D and E will contain the diagonal and superdiagonal elements of a bidiagonal matrix orthogonally equivalent to the one given as input. she got destroyed, RIP to her but she served her purpose 💀

VT — COMPLEX*16 array, dimension (LDVT, NCVT)

On entry, an N-by-NCVT matrix VT. On exit, VT is overwritten by P**H * VT. Not referenced if NCVT = 0. if NCVT = 0 she's literally not even invited to the function, she stays home 🏠

LDVT — INTEGER

The leading dimension of the array VT. LDVT >= max(1,N) if NCVT > 0; LDVT >= 1 if NCVT = 0.

U — COMPLEX*16 array, dimension (LDU, N)

On entry, an NRU-by-N matrix U. On exit, U is overwritten by U * Q. Not referenced if NRU = 0.

LDU — INTEGER

The leading dimension of the array U. LDU >= max(1,NRU).

C — COMPLEX*16 array, dimension (LDC, NCC)

On entry, an N-by-NCC matrix C. On exit, C is overwritten by Q**H * C. Not referenced if NCC = 0.

LDC — INTEGER

The leading dimension of the array C. LDC >= max(1,N) if NCC > 0; LDC >=1 if NCC = 0. (yes, that's LDC >=1 with no space, copy it exactly, don't @ me 🫶)

RWORK — DOUBLE PRECISION array, dimension (4*N)
INFO — INTEGER
- = 0: successful exit
- < 0: If INFO = -i, the i-th argument had an illegal value
- > 0: the algorithm did not converge; D and E contain the elements of a bidiagonal matrix which is orthogonally similar to the input matrix B; if INFO = i, i elements of E have not converged to zero.

ok so if INFO > 0 she did NOT converge and she's telling you how many elements of E are still out there living their truth instead of hitting zero. not ideal but she's honest about it 😭

✨ Internal Parameters ✨

TOLMUL — DOUBLE PRECISION, default = max(10,min(100,EPS**(-1/8)))

TOLMUL controls the convergence criterion of the QR loop.

If it is positive, TOLMUL*EPS is the desired relative precision in the computed singular values.
If it is negative, abs(TOLMUL*EPS*sigma_max) is the desired absolute accuracy in the computed singular values (corresponds to relative accuracy abs(TOLMUL*EPS) in the largest singular value.
abs(TOLMUL) should be between 1 and 1/EPS, and preferably between 10 (for fast convergence) and .1/EPS (for there to be some accuracy in the results).
Default is to lose at either one eighth or 2 of the available decimal digits in each computed singular value (whichever is smaller).

so basically she's the girl deciding how close is "close enough" and she has OPINIONS 💅✨

MAXITR — INTEGER, default = 6. MAXITR is the vibe-check on how many times the algorithm is allowed to loop through its inner loop. Bestie, if the number of passes through that inner loop goes over MAXITR*N**2, the algorithm literally stops — and yeah, that means it failed to converge. 😭 Not a slay.

✨ Author ✨

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🦋 subroutine zgghd3 🦋

   subroutine zgghd3 (character COMPQ, character COMPZ, integer N, integer ILO,
       integer IHI, complex*16, dimension( lda, * ) A, integer LDA, complex*16,
       dimension( ldb, * ) B, integer LDB, complex*16, dimension( ldq, * ) Q,
       integer LDQ, complex*16, dimension( ldz, * ) Z, integer LDZ, complex*16,
       dimension( * ) WORK, integer LWORK, integer INFO)
       ZGGHD3

🎀 Purpose 🎀

ZGGHD3 takes a pair of complex matrices (A,B) and reduces them to generalized upper Hessenberg form using unitary transformations — where A is a general matrix and B is upper triangular. The generalized eigenvalue problem is giving:

   A*x = lambda*B*x,

and B is typically made upper triangular by computing its QR factorization and moving the unitary matrix Q to the left side of the equation. Iconic behaviour, honestly. 💅

This subroutine simultaneously reduces A to a Hessenberg matrix H:

   Q**H*A*Z = H

and transforms B to another upper triangular matrix T:

   Q**H*B*Z = T

in order to reduce the problem to its standard form:

   H*y = lambda*T*y

where y = Z**H*x. Periodt. ✨

The unitary matrices Q and Z are determined as products of Givens rotations. They may either be formed explicitly, or they may be postmultiplied into input matrices Q1 and Z1, so that:

     Q1 * A * Z1**H = (Q1*Q) * H * (Z1*Z)**H
     Q1 * B * Z1**H = (Q1*Q) * T * (Z1*Z)**H

If Q1 is the unitary matrix from the QR factorization of B in the original equation A*x = lambda*B*x, then ZGGHD3 reduces the original problem to generalized Hessenberg form. 🫶

This is a blocked variant of CGGHRD, using matrix-matrix multiplications for parts of the computation to enhance performance. She's efficient, she's blocked, she ate. 🔥

🌸 Parameters 🌸

COMPQ — is CHARACTER*1.
- = 'N': do not compute Q;
- = 'I': Q is initialized to the unit matrix, and the unitary matrix Q is returned;
- = 'V': Q must contain a unitary matrix Q1 on entry, and the product Q1*Q is returned.
COMPZ — is CHARACTER*1.
- = 'N': do not compute Z;
- = 'I': Z is initialized to the unit matrix, and the unitary matrix Z is returned;
- = 'V': Z must contain a unitary matrix Z1 on entry, and the product Z1*Z is returned.
N — is INTEGER. The order of the matrices A and B. N >= 0. 💖
ILO — is INTEGER.
IHI — is INTEGER.

ILO and IHI mark the rows and columns of A which are to be reduced. It is assumed that A is already upper triangular in rows and columns 1:ILO-1 and IHI+1:N. ILO and IHI are normally set by a previous call to ZGGBAL; otherwise they should be set to 1 and N respectively. 1 <= ILO <= IHI <= N, if N > 0; ILO=1 and IHI=0, if N=0.

A — is COMPLEX*16 array, dimension (LDA, N).
- On entry, the N-by-N general matrix to be reduced.
- On exit, the upper triangle and the first subdiagonal of A are overwritten with the upper Hessenberg matrix H, and the rest is set to zero.
LDA — is INTEGER. The leading dimension of the array A. LDA >= max(1,N). ⭐
B — is COMPLEX*16 array, dimension (LDB, N).
- On entry, the N-by-N upper triangular matrix B.
- On exit, the upper triangular matrix T = Q**H B Z. The elements below the diagonal are set to zero.
LDB — is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
Q — is COMPLEX*16 array, dimension (LDQ, N).
- On entry, if COMPQ = 'V', the unitary matrix Q1, typically from the QR factorization of B.
- On exit, if COMPQ='I', the unitary matrix Q, and if COMPQ = 'V', the product Q1*Q.
- Not referenced if COMPQ='N'.
LDQ — is INTEGER. The leading dimension of the array Q. LDQ >= N if COMPQ='V' or 'I'; LDQ >= 1 otherwise.
Z — is COMPLEX*16 array, dimension (LDZ, N).
- On entry, if COMPZ = 'V', the unitary matrix Z1.
- On exit, if COMPZ='I', the unitary matrix Z, and if COMPZ = 'V', the product Z1*Z.
- Not referenced if COMPZ='N'.
LDZ — is INTEGER. The leading dimension of the array Z. LDZ >= N if COMPZ='V' or 'I'; LDZ >= 1 otherwise.
WORK — is COMPLEX*16 array, dimension (LWORK). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. 👑
LWORK — is INTEGER. The length of the array WORK. LWORK >= 1. For optimum performance LWORK >= 6*N*NB, where NB is the optimal blocksize.

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.

INFO — is INTEGER.
- = 0: successful exit. 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. 💀

💜 Author 💜

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🌈 Further Details 🌈

This routine reduces A to Hessenberg form and maintains B in triangular form using a blocked variant of Moler and Stewart's original algorithm, as described by Kagstrom, Kressner, Quintana-Orti, and Quintana-Orti (BIT 2008). the lore is real, bestie 📚

🧚 subroutine zgghrd 🧚

   subroutine zgghrd (character COMPQ, character COMPZ, integer N, integer ILO,
       integer IHI, complex*16, dimension( lda, * ) A, integer LDA, complex*16,
       dimension( ldb, * ) B, integer LDB, complex*16, dimension( ldq, * ) Q,
       integer LDQ, complex*16, dimension( ldz, * ) Z, integer LDZ, integer
       INFO)
       ZGGHRD

🎀 Purpose 🎀

ZGGHRD reduces a pair of complex matrices (A,B) to generalized upper Hessenberg form using unitary transformations, where A is a general matrix and B is upper triangular. The form of the generalized eigenvalue problem is:

   A*x = lambda*B*x,

and B is typically made upper triangular by computing its QR factorization and moving the unitary matrix Q to the left side of the equation. (Same energy as her sister routine, no cap. 🫶)

This subroutine simultaneously reduces A to a Hessenberg matrix H:

   Q**H*A*Z = H

and transforms B to another upper triangular matrix T:

   Q**H*B*Z = T

in order to reduce the problem to its standard form:

   H*y = lambda*T*y

where y = Z**H*x.

The unitary matrices Q and Z are determined as products of Givens rotations. They may either be formed explicitly, or they may be postmultiplied into input matrices Q1 and Z1, so that:

     Q1 * A * Z1**H = (Q1*Q) * H * (Z1*Z)**H
     Q1 * B * Z1**H = (Q1*Q) * T * (Z1*Z)**H

If Q1 is the unitary matrix from the QR factorization of B in the original equation A*x = lambda*B*x, then ZGGHRD reduces the original problem to generalized Hessenberg form. ✨

🌸 Parameters 🌸

COMPQ — is CHARACTER*1.
- = 'N': do not compute Q;
- = 'I': Q is initialized to the unit matrix, and the unitary matrix Q is returned;
- = 'V': Q must contain a unitary matrix Q1 on entry, and the product Q1*Q is returned.
COMPZ — is CHARACTER*1.
- = 'N': do not compute Z;
- = 'I': Z is initialized to the unit matrix, and the unitary matrix Z is returned;
- = 'V': Z must contain a unitary matrix Z1 on entry, and the product Z1*Z is returned.
N — is INTEGER. The order of the matrices A and B. N >= 0. 💖
ILO — is INTEGER.
IHI — is INTEGER.

A — is COMPLEX*16 array, dimension (LDA, N).
- On entry, the N-by-N general matrix to be reduced.
- On exit, the upper triangle and the first subdiagonal of A are overwritten with the upper Hessenberg matrix H, and the rest is set to zero.
LDA — is INTEGER. The leading dimension of the array A. LDA >= max(1,N). ⭐
B — is COMPLEX*16 array, dimension (LDB, N).
- On entry, the N-by-N upper triangular matrix B.
- On exit, the upper triangular matrix T = Q**H B Z. The elements below the diagonal are set to zero.
LDB — is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
Q — is COMPLEX*16 array, dimension (LDQ, N).
- On entry, if COMPQ = 'V', the unitary matrix Q1, typically from the QR factorization of B.
- On exit, if COMPQ='I', the unitary matrix Q, and if COMPQ = 'V', the product Q1*Q.
- Not referenced if COMPQ='N'.
LDQ — is INTEGER. The leading dimension of the array Q. LDQ >= N if COMPQ='V' or 'I'; LDQ >= 1 otherwise.
Z
Z — this one's a COMPLEX*16 array, dimension (LDZ, N). On entry, if COMPZ = 'V', it holds the unitary matrix Z1. On exit, if COMPZ='I' you get the unitary matrix Z, and if COMPZ = 'V' you get the product Z1*Z. And if COMPZ='N'? bestie, it is not referenced, we simply do not look at it 💅
LDZ — an INTEGER, the leading dimension of the array Z. LDZ >= N if COMPZ='V' or 'I'; LDZ >= 1 otherwise.
INFO — INTEGER, the vibe report 📋
- = 0: successful exit, we ate ✨
- < 0: if INFO = -i, the i-th argument had an illegal value. Rude of you, honestly.

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details

This routine reduces A to Hessenberg and B to triangular form by an unblocked reduction, as described in Matrix Computations, by Golub and van Loan (Johns Hopkins Press). No cap, that's literally the citation 🎀

🌈 subroutine `zggqrf`

subroutine zggqrf (integer N, integer M, integer P, complex*16, dimension(
    lda, * ) A, integer LDA, complex*16, dimension( * ) TAUA, complex*16,
    dimension( ldb, * ) B, integer LDB, complex*16, dimension( * ) TAUB,
    complex*16, dimension( * ) WORK, integer LWORK, integer INFO)

ZGGQRF — say it with me, generalized QR factorization, and yes it's giving main character energy 👑

🎯 Purpose

ZGGQRF computes a generalized QR factorization of an N-by-M matrix A and an N-by-P matrix B:

            A = Q*R,        B = Q*T*Z,

where Q is an N-by-N unitary matrix, Z is a P-by-P unitary matrix, and R and T assume one of the forms:

            if N >= M,  R = ( R11 ) M  ,   or if N < M,  R = ( R11  R12 ) N,
                            (  0  ) N-M                         N   M-N
                               M

where R11 is upper triangular, and

            if N <= P,  T = ( 0  T12 ) N,   or if N > P,  T = ( T11 ) N-P,
                             P-N  N                           ( T21 ) P
                                                                 P

where T12 or T21 is upper triangular.

In particular, if B is square and nonsingular, the GQR factorization of A and B implicitly gives the QR factorization of inv(B)*A:

                         inv(B)*A = Z**H * (inv(T)*R)

where inv(B) denotes the inverse of the matrix B, and Z**H denotes the conjugate transpose of matrix Z. Sneaky little identity, iconic behavior 💖

🧩 Parameters

N — INTEGER. The number of rows of the matrices A and B. N >= 0.
M — INTEGER. The number of columns of the matrix A. M >= 0.
P — INTEGER. The number of columns of the matrix B. P >= 0.
A — COMPLEX*16 array, dimension (LDA,M). On entry, the N-by-M matrix A. On exit, the elements on and above the diagonal of the array contain the min(N,M)-by-M upper trapezoidal matrix R (R is upper triangular if N >= M); the elements below the diagonal, together with the array TAUA, represent the unitary matrix Q as a product of min(N,M) elementary reflectors (peep Further Details, bestie).
LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,N).
TAUA — COMPLEX*16 array, dimension (min(N,M)). The scalar factors of the elementary reflectors which represent the unitary matrix Q (see Further Details).
B — COMPLEX*16 array, dimension (LDB,P). On entry, the N-by-P matrix B. On exit, if N <= P, the upper triangle of the subarray B(1:N,P-N+1:P) contains the N-by-N upper triangular matrix T; if N > P, the elements on and above the (N-P)-th subdiagonal contain the N-by-P upper trapezoidal matrix T; the remaining elements, with the array TAUB, represent the unitary matrix Z as a product of elementary reflectors (see Further Details).
LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,N).
TAUB — COMPLEX*16 array, dimension (min(N,P)). The scalar factors of the elementary reflectors which represent the unitary matrix Z (see Further Details).
WORK — COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. ✨
LWORK — INTEGER. The dimension of the array WORK. LWORK >= max(1,N,M,P). For optimum performance LWORK >= max(N,M,P)*max(NB1,NB2,NB3), where NB1 is the optimal blocksize for the QR factorization of an N-by-M matrix, NB2 is the optimal blocksize for the RQ factorization of an N-by-P matrix, and NB3 is the optimal blocksize for a call of ZUNMQR.

INFO — INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value.

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details

The matrix Q is represented as a product of elementary reflectors

                Q = H(1) H(2) . . . H(k), where k = min(n,m).

Each H(i) has the form

                H(i) = I - taua * v * v**H

where taua is a complex scalar, and v is a complex vector with v(1:i-1) = 0 and v(i) = 1; v(i+1:n) is stored on exit in A(i+1:n,i), and taua in TAUA(i). To form Q explicitly, use LAPACK subroutine ZUNGQR. To use Q to update another matrix, use LAPACK subroutine ZUNMQR.

The matrix Z is represented as a product of elementary reflectors

                Z = H(1) H(2) . . . H(k), where k = min(n,p).

Each H(i) has the form

                H(i) = I - taub * v * v**H

where taub is a complex scalar, and v is a complex vector with v(p-k+i+1:p) = 0 and v(p-k+i) = 1; v(1:p-k+i-1) is stored on exit in B(n-k+i,1:p-k+i-1), and taub in TAUB(i). To form Z explicitly, use LAPACK subroutine ZUNGRQ. To use Z to update another matrix, use LAPACK subroutine ZUNMRQ.

🦋 subroutine `zggrqf`

subroutine zggrqf (integer M, integer P, integer N, complex*16, dimension(
    lda, * ) A, integer LDA, complex*16, dimension( * ) TAUA, complex*16,
    dimension( ldb, * ) B, integer LDB, complex*16, dimension( * ) TAUB,
    complex*16, dimension( * ) WORK, integer LWORK, integer INFO)

ZGGRQF — the RQ sibling, and yes, the argument order is M, P, N. We love a plot twist 🌸

🎯 Purpose

ZGGRQF computes a generalized RQ factorization of an M-by-N matrix A and a P-by-N matrix B:

                        A = R*Q,        B = Z*T*Q,

where Q is an N-by-N unitary matrix, Z is a P-by-P unitary matrix, and R and T assume one of the forms:

            if M <= N,  R = ( 0  R12 ) M,   or if M > N,  R = ( R11 ) M-N,
                             N-M  M                           ( R21 ) N
                                                                 N

where R12 or R21 is upper triangular, and

            if P >= N,  T = ( T11 ) N  ,   or if P < N,  T = ( T11  T12 ) P,
                            (  0  ) P-N                         P   N-P
                               N

where T11 is upper triangular.

In particular, if B is square and nonsingular, the GRQ factorization of A and B implicitly gives the RQ factorization of A*inv(B):

                         A*inv(B) = (R*inv(T))*Z**H

where inv(B) denotes the inverse of the matrix B, and Z**H denotes the conjugate transpose of matrix Z. Same energy, mirrored, and we're obsessed 💜

🧩 Parameters

M — INTEGER. The number of rows of the matrix A. M >= 0.
P — INTEGER. The number of rows of the matrix B. P >= 0.
N — INTEGER. The number of columns of the matrices A and B. N >= 0.
A — COMPLEX*16 array, dimension (LDA,N). On entry, the M-by-N matrix A. On exit, if M <= N, the upper triangle of the subarray A(1:M,N-M+1:N) contains the M-by-M upper triangular matrix R; if M > N, the elements on and above the (M-N)-th subdiagonal contain the M-by-N upper trapezoidal matrix R; the remaining elements, with the array TAUA, represent the unitary matrix Q as a product of elementary reflectors (see Further Details).
LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,M).
TAUA — COMPLEX*16 array, dimension (min(M,N)). The scalar factors of the elementary reflectors which represent the unitary matrix Q (see Further Details).
B — COMPLEX*16 array, dimension (LDB,N). On entry, the P-by-N matrix B. On exit, the elements on and above the diagonal of the array contain the min(P,N)-by-N upper trapezoidal matrix T (T is upper triangular if P >= N); the elements below the diagonal, with the array TAUB, represent the unitary matrix Z as a product of elementary reflectors (see Further Details).
LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,P).
TAUB — COMPLEX*16 array, dimension (min(P,N)). The scalar factors of the elementary reflectors which represent the unitary matrix Z (see Further Details).
WORK — COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. ⭐
LWORK — INTEGER. The dimension of the array WORK. LWORK >= max(1,N,M,P). For optimum performance LWORK >= max(N,M,P)*max(NB1,NB2,NB3), where NB1 is the optimal blocksize for the RQ factorization of an M-by-N matrix, NB2 is the optimal blocksize for the QR factorization of a P-by-N matrix, and NB3 is the optimal blocksize for a call of ZUNMRQ.

INFO — INTEGER, and this is the vibe check at the end 😌
- = 0: successful exit ✨
- < 0: if INFO=-i, the i-th argument had an illegal value. somebody passed a bad argument, iconic behavior, not in the good way 🙈

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

four whole institutions in the group chat, no cap 🫶

🔍 Further Details:

Okay bestie, here's the tea on how the matrix Q gets built ☕ — it's a product of elementary reflectors, and it's giving very much "factorization era":

   Q = H(1) H(2) . . . H(k), where k = min(m,n).

and each individual H(i) looks like this:

   H(i) = I - taua * v * v**H

where taua is a complex scalar, and v is a complex vector with

   v(n-k+i+1:n) = 0 and v(n-k+i) = 1;

v(1:n-k+i-1) is stored on exit in A(m-k+i,1:n-k+i-1), and taua in TAUA(i).

Wanna form Q explicitly? Use LAPACK subroutine ZUNGRQ. 💖
Wanna use Q to update another matrix? Use LAPACK subroutine ZUNMRQ. 🦋

And now for the matrix Z, same energy, different letters 🎀:

   Z = H(1) H(2) . . . H(k), where k = min(p,n).

each H(i) has the form:

   H(i) = I - taub * v * v**H

where taub is a complex scalar, and v is a complex vector with

   v(1:i-1) = 0 and v(i) = 1;

v(i+1:p) is stored on exit in B(i+1:p,i), and taub in TAUB(i).

To form Z explicitly, use LAPACK subroutine ZUNGQR. 💜
To use Z to update another matrix, use LAPACK subroutine ZUNMQR. ⭐

🌸 subroutine zggsvp3

subroutine zggsvp3 (character JOBU, character JOBV, character JOBQ, integer
    M, integer P, integer N, complex*16, dimension( lda, * ) A, integer LDA,
    complex*16, dimension( ldb, * ) B, integer LDB, double precision TOLA,
    double precision TOLB, integer K, integer L, complex*16, dimension( ldu,
    * ) U, integer LDU, complex*16, dimension( ldv, * ) V, integer LDV,
    complex*16, dimension( ldq, * ) Q, integer LDQ, integer, dimension( * )
    IWORK, double precision, dimension( * ) RWORK, complex*16, dimension( *
    ) TAU, complex*16, dimension( * ) WORK, integer LWORK, integer INFO)

ZGGSVP3 — say it with me, it's the GSVD pregame 🥳

🎯 Purpose:

ZGGSVP3 computes unitary matrices U, V and Q such that — ok look at this glow-up, bestie:

                           N-K-L  K    L
         U**H*A*Q =     K ( 0    A12  A13 )  if M-K-L >= 0;
                        L ( 0     0   A23 )
                    M-K-L ( 0     0    0  )

                         N-K-L  K    L
                =     K ( 0    A12  A13 )  if M-K-L < 0;
                    M-K ( 0     0   A23 )

                         N-K-L  K    L
         V**H*B*Q =   L ( 0     0   B13 )
                    P-L ( 0     0    0  )

where the K-by-K matrix A12 and L-by-L matrix B13 are nonsingular upper triangular; A23 is L-by-L upper triangular if M-K-L >= 0, otherwise A23 is (M-K)-by-L upper trapezoidal. K+L = the effective numerical rank of the (M+P)-by-N matrix (A**H,B**H)**H. big rank energy, we love to see it 👑

This decomposition is the preprocessing step for computing the Generalized Singular Value Decomposition (GSVD), see subroutine ZGGSVD3. (it's the opening act, the main character comes later ✨)

🛠 Parameters

JOBU — JOBU is CHARACTER*1
- = 'U': Unitary matrix U is computed; ✅
- = 'N': U is not computed. (we're skipping it, respectfully)
JOBV — JOBV is CHARACTER*1
- = 'V': Unitary matrix V is computed;
- = 'N': V is not computed.
JOBQ — JOBQ is CHARACTER*1
- = 'Q': Unitary matrix Q is computed;
- = 'N': Q is not computed.
M — M is INTEGER
- The number of rows of the matrix A. M >= 0.
P — P is INTEGER
- The number of rows of the matrix B. P >= 0.
N — N is INTEGER
- The number of columns of the matrices A and B. N >= 0.
A — A is COMPLEX*16 array, dimension (LDA,N)
- On entry, the M-by-N matrix A.
- On exit, A contains the triangular (or trapezoidal) matrix described in the Purpose section. (glow up: entry vs exit, she's different now 💅)
LDA — LDA is INTEGER
- The leading dimension of the array A. LDA >= max(1,M).
B — B is COMPLEX*16 array, dimension (LDB,N)
- On entry, the P-by-N matrix B.
- On exit, B contains the triangular matrix described in the Purpose section.
LDB — LDB is INTEGER
- The leading dimension of the array B. LDB >= max(1,P).
TOLA — TOLA is DOUBLE PRECISION
TOLB — TOLB is DOUBLE PRECISION
- TOLA and TOLB are the thresholds to determine the effective numerical rank of matrix B and a subblock of A. Generally, they are set to

   TOLA = MAX(M,N)*norm(A)*MAZHEPS,
   TOLB = MAX(P,N)*norm(B)*MAZHEPS.

The size of TOLA and TOLB may affect the size of backward errors of the decomposition. (choose wisely, bestie, these lil numbers move the needle 😭)

K — K is INTEGER
L — L is INTEGER
- On exit, K and L specify the dimension of the subblocks described in Purpose section.
- K + L = effective numerical rank of (A**H,B**H)**H.
U — U is COMPLEX*16 array, dimension (LDU,M)
- If JOBU = 'U', U contains the unitary matrix U.
- If JOBU = 'N', U is not referenced.
LDU — LDU is INTEGER
- The leading dimension of the array U. LDU >= max(1,M) if JOBU = 'U'; LDU >= 1 otherwise.
V — V is COMPLEX*16 array, dimension (LDV,P)
- If JOBV = 'V', V contains the unitary matrix V.
- If JOBV = 'N', V is not referenced.
LDV — LDV is INTEGER
- The leading dimension of the array V. LDV >= max(1,P) if JOBV = 'V'; LDV >= 1 otherwise.
Q — Q is COMPLEX*16 array, dimension (LDQ,N)
- If JOBQ = 'Q', Q contains the unitary matrix Q.
- If JOBQ = 'N', Q is not referenced.
LDQ — LDQ is INTEGER
- The leading dimension of the array Q. LDQ >= max(1,N) if JOBQ = 'Q'; LDQ >= 1 otherwise.
IWORK — IWORK is INTEGER array, dimension (N)
RWORK — RWORK is DOUBLE PRECISION array, dimension (2*N)
TAU — TAU is COMPLEX*16 array, dimension (N)
WORK — WORK is COMPLEX*16 array, dimension (MAX(1,LWORK))
- On exit, if INFO = 0, WORK(1) returns the optimal LWORK. ✨
LWORK — LWORK is INTEGER
- The dimension of the array WORK.
- If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. (window shopping for array sizes again, we stan a frugal queen 💅)
INFO — INFO is INTEGER
- = 0: successful exit. ✨
- < 0: if INFO = -i, the i-th argument had an illegal value. bad argument alert 🚨

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details:

The subroutine uses LAPACK subroutine ZGEQP3 for the QR factorization with column pivoting to detect the effective numerical rank of the a matrix. It may be replaced by a better rank determination strategy. (honest queen behavior — she's literally telling us she could be improved 😭)

ZGGSVP3 replaces the deprecated subroutine ZGGSVP. (bye boo, you're old news 🫶)

🦋 subroutine zgsvj0

subroutine zgsvj0 (character*1 JOBV, integer M, integer N, complex*16,
    dimension( lda, * ) A, integer LDA, complex*16, dimension( n ) D, double
    precision, dimension( n ) SVA, integer MV, complex*16, dimension( ldv, *
    ) V, integer LDV, double precision EPS, double precision SFMIN, double
    precision TOL, integer NSWEEP, complex*16, dimension( lwork ) WORK,
    integer LWORK, integer INFO)

ZGSVJ0 — pre-processor for the routine zgesvj. (the opening act before the headliner, we love a supportive bestie 🌸)

🎯 Purpose:

ZGSVJ0 is called from ZGESVJ as a pre-processor and that is its main purpose. It applies Jacobi rotations in the same way as ZGESVJ does, but it does not check convergence (stopping criterion). Few tuning parameters (marked by [TP]) are available for the implementer. (no stopping criterion? she just goes until she's told to stop, main character energy fr fr 😌)

🛠 Parameters

JOBV — JOBV is CHARACTER*1
- Specifies whether the output from this procedure is used to compute the matrix V:
- = 'V': the product of the Jacobi rotations is accumulated by postmulyiplying the N-by-N array V. (See the description of V.)
- = 'A': the product of the Jacobi rotations is accumulated by postmulyiplying the MV-by-N array V. (See the descriptions of MV and V.)
- = 'N': the Jacobi rotations are not accumulated. (we're not collecting them, just vibes)
M — M is INTEGER
- The number of rows of the input matrix A. M >= 0.
N — N is INTEGER
- The number of columns of the input matrix A. M >= N >= 0.
A — A is COMPLEX*16 array, dimension (LDA,N)
- On entry, M-by-N matrix A, such that A*diag(D) represents the input matrix.
- On exit, A_onexit * diag(D_onexit) represents the input matrix A*diag(D) post-multiplied by a sequence of Jacobi rotations, where the rotation threshold and the total number of sweeps are given in TOL and NSWEEP, respectively. (See the descriptions of D, TOL and NSWEEP.)
LDA — LDA is INTEGER
- The leading dimension of the array A. LDA >= max(1,M).
D — D is COMPLEX*16 array, dimension (N)
- The array D accumulates the scaling factors from the complex scaled Jacobi rotations.
- On entry, A*diag(D) represents the input matrix.
- On exit, A_onexit*diag(D_onexit) represents the input matrix post-multiplied by a sequence of Jacobi rotations, where the rotation threshold and the total number of sweeps are given in TOL and NSWEEP, respectively. (See the descriptions of A, TOL and NSWEEP.)
SVA —
SVA — a DOUBLE PRECISION array, dimension (N) ✨ On entry, SVA is holding the Euclidean norms of the columns of the matrix A*diag(D). On exit, SVA holds the Euclidean norms of the columns of the matrix A_onexit*diag(D_onexit). She updates herself in place, iconic behavior fr 💅
MV — an INTEGER 🦋
- If JOBV = 'A', then MV rows of V are post-multipled by a sequence of Jacobi rotations.
- If JOBV = 'N', then MV is not referenced.
V — a COMPLEX*16 array, dimension (LDV,N) 🌸
- If JOBV = 'V' then N rows of V are post-multipled by a sequence of Jacobi rotations.
- If JOBV = 'A' then MV rows of V are post-multipled by a sequence of Jacobi rotations.
- If JOBV = 'N', then V is not referenced.
LDV — an INTEGER 👑 The leading dimension of the array V, so LDV >= 1. And also: if JOBV = 'V', then LDV >= N. If JOBV = 'A', then LDV >= MV.
EPS — a DOUBLE PRECISION 🍓 and EPS = DLAMCH('Epsilon'). That's literally it bestie.
SFMIN — a DOUBLE PRECISION 🍓 and SFMIN = DLAMCH('Safe Minimum'). Periodt.
TOL — a DOUBLE PRECISION 🧚 TOL is the threshold for Jacobi rotations. So for a pair A(:,p), A(:,q) of pivot columns, the Jacobi rotation is applied only if ABS(COS(angle(A(:,p),A(:,q)))) > TOL. Like, if the angle's cosine doesn't clear the bar, she's not rotating, no cap 💀
NSWEEP — an INTEGER 🌈 NSWEEP is the number of sweeps of Jacobi rotations to be performed. That's the count, that's the vibe.
WORK — a COMPLEX*16 array, dimension (LWORK) ✨
LWORK — an INTEGER 🦋 LWORK is the dimension of WORK. And LWORK >= M. Don't be stingy with the workspace, bestie 🙈
INFO — an INTEGER 👑 the moment of truth:
- = 0: successful exit. Slay 🎀
- < 0: if INFO = -i, then the i-th argument had an illegal value. Not her fault, it's the input's fault 💅

Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details: 🔥

ZGSVJ0 is used just to enable ZGESVJ to call a simplified version of itself to work on a submatrix of the original matrix. Like a little mini-me of the algorithm, and honestly? Main character energy 🫶

Contributor: 🌸

Zlatko Drmac (Zagreb, Croatia)

Bugs, Examples and Comments: 💌

Please report all bugs and send interesting test examples and comments to drmac@math.hr. Thank you. Fr fr, they want to hear from you 🦋

subroutine zgsvj1 🧚

subroutine zgsvj1 (character*1 JOBV, integer M, integer N, integer N1,
    complex*16, dimension( lda, * ) A, integer LDA, complex*16, dimension( n
    ) D, double precision, dimension( n ) SVA, integer MV, complex*16,
    dimension( ldv, * ) V, integer LDV, double precision EPS, double
    precision SFMIN, double precision TOL, integer NSWEEP, complex*16,
    dimension( lwork ) WORK, integer LWORK, integer INFO)

ZGSVJ1 pre-processor for the routine zgesvj, applies Jacobi rotations targeting only particular pivots. ✨

Purpose: 👑

ZGSVJ1 is called from ZGESVJ as a pre-processor and that is its main purpose. It applies Jacobi rotations in the same way as ZGESVJ does, but it targets only particular pivots and it does not check convergence (stopping criterion). Few tuning parameters (marked by [TP]) are available for the implementer.

Further Details 🌈

ZGSVJ1 applies few sweeps of Jacobi rotations in the column space of the input M-by-N matrix A. The pivot pairs are taken from the (1,2) off-diagonal block in the corresponding N-by-N Gram matrix A^T * A. The block-entries (tiles) of the (1,2) off-diagonal block are marked by the [x]'s in the following scheme:

   | *  *  * [x] [x] [x]|
   | *  *  * [x] [x] [x]|    Row-cycling in the nblr-by-nblc [x] blocks.
   | *  *  * [x] [x] [x]|    Row-cyclic pivoting inside each [x] block.
   |[x] [x] [x] *  *  * |
   |[x] [x] [x] *  *  * |
   |[x] [x] [x] *  *  * |

In terms of the columns of A, the first N1 columns are rotated 'against' the remaining N-N1 columns, trying to increase the angle between the corresponding subspaces. The off-diagonal block is N1-by-(N-N1) and it is tiled using quadratic tiles of side KBL. Here, KBL is a tuning parameter. The number of sweeps is given in NSWEEP and the orthogonality threshold is given in TOL. Lowkey a whole choreography 💅

Parameters 🎀

JOBV — a CHARACTER*1 🦋 Specifies whether the output from this procedure is used to compute the matrix V:
- = 'V': the product of the Jacobi rotations is accumulated by postmulyiplying the N-by-N array V. (See the description of V.)
- = 'A': the product of the Jacobi rotations is accumulated by postmulyiplying the MV-by-N array V. (See the descriptions of MV and V.)
- = 'N': the Jacobi rotations are not accumulated. (So no V for you, sorry bestie 🙈)
M — an INTEGER 🌸 The number of rows of the input matrix A. M >= 0.
N — an INTEGER 🌸 The number of columns of the input matrix A. M >= N >= 0.
N1 — an INTEGER 💜 N1 specifies the 2 x 2 block partition, the first N1 columns are rotated 'against' the remaining N-N1 columns of A.
A — a COMPLEX*16 array, dimension (LDA,N) ✨ On entry, M-by-N matrix A, such that A*diag(D) represents the input matrix. On exit, A_onexit * D_onexit represents the input matrix A*diag(D) post-multiplied by a sequence of Jacobi rotations, where the rotation threshold and the total number of sweeps are given in TOL and NSWEEP, respectively. (See the descriptions of N1, D, TOL and NSWEEP.) She goes in one way and comes out transformed, it's giving glow-up 🌈
LDA — an INTEGER 👑 The leading dimension of the array A. LDA >= max(1,M).
D — a COMPLEX*16 array, dimension (N) 🍓 The array D accumulates the scaling factors from the fast scaled Jacobi rotations. On entry, A*diag(D) represents the input matrix. On exit, A_onexit*diag(D_onexit) represents the input matrix post-multiplied by a sequence of Jacobi rotations, where the rotation threshold and the total number of sweeps are given in TOL and NSWEEP, respectively. (See the descriptions of N1, A, TOL and NSWEEP.)
SVA — a DOUBLE PRECISION array, dimension (N) 💖 On entry, SVA contains the Euclidean norms of the columns of the matrix A*diag(D). On exit, SVA contains the Euclidean norms of the columns of the matrix onexit*diag(D_onexit). (Yes, exactly like it says — onexit, no cap 😭)
MV — an INTEGER 🦋
- If JOBV = 'A', then MV rows of V are post-multipled by a sequence of Jacobi rotations.
- If JOBV = 'N', then MV is not referenced.
V — a COMPLEX*16 array, dimension (LDV,N) 🌸
- If JOBV = 'V' then N rows of V are post-multipled by a sequence of Jacobi rotations.
- If JOBV = 'A' then MV rows of V are post-multipled by a sequence of Jacobi rotations.
- If JOBV = 'N', then V is not referenced.
LDV — an INTEGER 👑 The leading dimension of the array V, so LDV >= 1. If JOBV = 'V', LDV >= N. If JOBV = 'A', LDV >= MV.
EPS — a DOUBLE PRECISION 🧚 EPS = DLAMCH('Epsilon')
SFMIN — a DOUBLE PRECISION 🧚 SFMIN = DLAMCH('Safe Minimum')
TOL — a DOUBLE PRECISION 🍓 TOL is the threshold for Jacobi rotations. For a pair A(:,p), A(:,q) of pivot columns, the Jacobi rotation is applied only if ABS(COS(angle(A(:,p),A(:,q)))) > TOL.
NSWEEP — an INTEGER 🌈 NSWEEP is the number of sweeps of Jacobi rotations to be performed.
WORK — a COMPLEX*16 array, dimension (LWORK) ✨
LWORK — an INTEGER 💜 LWORK is the dimension of WORK. LWORK >= M.
INFO — an INTEGER 👑
- = 0: successful exit. We love to see it 🎀
- < 0: if INFO = -i, then the i-th argument had an illegal value

Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Contributor: 💖

Zlatko Drmac (Zagreb, Croatia)

subroutine zhbgst 🦋

subroutine zhbgst (character VECT, character UPLO, integer N, integer KA,
    integer KB, complex*16, dimension( ldab, * ) AB, integer LDAB,
    complex*16, dimension( ldbb, * ) BB, integer LDBB, complex*16,
    dimension( ldx, * ) X, integer LDX, complex*16, dimension( * ) WORK,
    double precision, dimension( * ) RWORK, integer INFO)

ZHBGST ✨

Purpose: 👑

ZHBGST reduces a complex Hermitian-definite banded generalized eigenproblem A*x = lambda*B*x to standard form C*y = lambda*y, such that C has the same bandwidth as A. Bestie she's reshaping the whole problem and keeping the bandwidth intact, that's the whole flex 💅

B must have been previously factorized as S**H*S by ZPBSTF, using a split Cholesky factorization. A is overwritten by C = X**H*A*X, where X = S**(-1)*Q and Q is a unitary matrix chosen to preserve the bandwidth of A. So A? Gone. Overwritten. She lives there now 🔥

Parameters 🌸

VECT — a CHARACTER*1 🦋
- = 'N': do not form the transformation matrix X;
- = 'V': form X.
UPLO — a CHARACTER*1 💜
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — an INTEGER 👑 The order of the matrices A and B. N >= 0.
KA — an INTEGER ✨ The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KA >= 0.
KB — an INTEGER 🌈 The number of superdiagonals of the matrix B if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KA >= KB >= 0.
AB
AB — a COMPLEX*16 array, dimension (LDAB,N). On entry, bestie, this holds the upper or lower triangle of the Hermitian band matrix A, and it lives in the first ka+1 rows of the array. The j-th column of A sits in the j-th column of AB, like this:
- if UPLO = 'U', AB(ka+1+i-j,j) = A(i,j) for max(1,j-ka)<=i<=j;
- if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+ka).

On exit? The transformed matrix X**H*A*X, stored in the same format as A. Glow up complete. ✨

LDAB — an INTEGER. The leading dimension of the array AB. Rule of thumb: LDAB >= KA+1. No exceptions, she's strict. 💅
BB — a COMPLEX*16 array, dimension (LDBB,N). This is the banded factor S from the split Cholesky factorization of B, exactly as returned by ZPBSTF, stored in the first kb+1 rows of the array.
LDBB — an INTEGER. The leading dimension of the array BB. LDBB >= KB+1. 🎀
X — a COMPLEX*16 array, dimension (LDX,N).
- If VECT = 'V', this is the n-by-n matrix X.
- If VECT = 'N', the array X is literally not referenced — she's off the clock. 😴
LDX — an INTEGER. The leading dimension of the array X. LDX >= max(1,N) if VECT = 'V'; LDX >= 1 otherwise.
WORK — a COMPLEX*16 array, dimension (N). The lil scratchpad. 🧚
RWORK — a DOUBLE PRECISION array, dimension (N). Her real-valued bestie.
INFO — an INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. Somebody messed up and it wasn't me. 💀

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine `zhbtrd` 🔥

subroutine zhbtrd (character VECT, character UPLO, integer N, integer KD,
    complex*16, dimension( ldab, * ) AB, integer LDAB, double precision,
    dimension( * ) D, double precision, dimension( * ) E, complex*16,
    dimension( ldq, * ) Q, integer LDQ, complex*16, dimension( * ) WORK,
    integer INFO)

ZHBTRD — say it with me, bestie.

Purpose:

ZHBTRD reduces a complex Hermitian band matrix A to real symmetric tridiagonal form T by a unitary similarity transformation: Q**H * A * Q = T. It's giving makeover montage. 💖

Parameters

VECT — a CHARACTER*1.
- = 'N': do not form Q;
- = 'V': form Q;
- = 'U': update a matrix X, by forming X*Q.
UPLO — a CHARACTER*1.
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — an INTEGER. The order of the matrix A. N >= 0.
KD — an INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
AB — a COMPLEX*16 array, dimension (LDAB,N). On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:
- if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
- if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).

On exit, the diagonal elements of AB are overwritten by the diagonal elements of the tridiagonal matrix T; if KD > 0, the elements on the first superdiagonal (if UPLO = 'U') or the first subdiagonal (if UPLO = 'L') are overwritten by the off-diagonal elements of T; the rest of AB is overwritten by values generated during the reduction. She's a whole different girl now. 💅

LDAB — an INTEGER. The leading dimension of the array AB. LDAB >= KD+1.
D — a DOUBLE PRECISION array, dimension (N). The diagonal elements of the tridiagonal matrix T. Main character energy only. 👑
E — a DOUBLE PRECISION array, dimension (N-1). The off-diagonal elements of the tridiagonal matrix T: E(i) = T(i,i+1) if UPLO = 'U'; E(i) = T(i+1,i) if UPLO = 'L'.
Q — a COMPLEX*16 array, dimension (LDQ,N).
- On entry, if VECT = 'U', then Q must contain an N-by-N matrix X; if VECT = 'N' or 'V', then Q need not be set.
- On exit:
  - if VECT = 'V', Q contains the N-by-N unitary matrix Q;
  - if VECT = 'U', Q contains the product X*Q;
  - if VECT = 'N', the array Q is not referenced. She's not even in the group chat. 🙈
LDQ — an INTEGER. The leading dimension of the array Q. LDQ >= 1, and LDQ >= N if VECT = 'V' or 'U'.
WORK — a COMPLEX*16 array, dimension (N).
INFO — an INTEGER.
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

Further Details:

Modified by Linda Kaufman, Bell Labs. Shoutout to her, fr fr. 🫶

subroutine `zhetrd_hb2st` 🌈

subroutine zhetrd_hb2st (character STAGE1, character VECT, character UPLO,
    integer N, integer KD, complex*16, dimension( ldab, * ) AB, integer
    LDAB, double precision, dimension( * ) D, double precision, dimension( *
    ) E, complex*16, dimension( * ) HOUS, integer LHOUS, complex*16,
    dimension( * ) WORK, integer LWORK, integer INFO)

ZHETRD_HB2ST reduces a complex Hermitian band matrix A to real symmetric tridiagonal form T.

Purpose:

ZHETRD_HB2ST reduces a complex Hermitian band matrix A to real symmetric tridiagonal form T by a unitary similarity transformation: Q**H * A * Q = T. Same vibe, different routine. 🦋

Parameters

STAGE1 — a CHARACTER*1.
- = 'N': 'No': to mention that the stage 1 of the reduction from dense to band using the zhetrd_he2hb routine was not called before this routine to reproduce AB. In other term this routine is called as standalone.
- = 'Y': 'Yes': to mention that the stage 1 of the reduction from dense to band using the zhetrd_he2hb routine has been called to produce AB (e.g., AB is the output of zhetrd_he2hb.
VECT — a CHARACTER*1.
- = 'N': No need for the Housholder representation, and thus LHOUS is of size max(1, 4*N);
- = 'V': the Householder representation is needed to either generate or to apply Q later on, then LHOUS is to be queried and computed. (NOT AVAILABLE IN THIS RELEASE).

Heads up bestie: that 'V' option? NOT AVAILABLE IN THIS RELEASE. Do not come for her, she said what she said. 💀

UPLO — a CHARACTER*1.
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — an INTEGER. The order of the matrix A. N >= 0.
KD — an INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
AB — a COMPLEX*16 array, dimension (LDAB,N). On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:
- if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
- if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).

LDAB — an INTEGER. The leading dimension of the array AB. LDAB >= KD+1.
D — a DOUBLE PRECISION array, dimension (N). The diagonal elements of the tridiagonal matrix T.
E — a DOUBLE PRECISION array, dimension (N-1). The off-diagonal elements of the tridiagonal matrix T: E(i) = T(i,i+1) if UPLO = 'U'; E(i) = T(i+1,i) if UPLO = 'L'.
HOUS — a COMPLEX*16 array, dimension LHOUS, that store the Householder representation. She's keeping receipts. 🧾
LHOUS — an INTEGER. The dimension of the array HOUS. LHOUS = MAX(1, dimension). If LWORK = -1, or LHOUS=-1, then a query is assumed; the routine only calculates the optimal size of the HOUS array, returns this value as the first entry of the HOUS array, and no error message related to LHOUS is issued by XERBLA. LHOUS = MAX(1, dimension) where
- dimension = 4*N if VECT='N'
- not available now if VECT='H'
WORK — a COMPLEX*16 array, dimension LWORK.
LWORK — an INTEGER. The dimension of the array WORK. LWORK = MAX(1, dimension). If LWORK = -1, or LHOUS=-1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. LWORK = MAX(1, dimension) where
- dimension = (2KD+1)*N + KD*NTHREADS
- where KD is the blocking size of the reduction,
- FACTOPTNB is the blocking used by the QR or LQ algorithm, usually FACTOPTNB=128 is a good choice
- NTHREADS is the number of threads used when openMP compilation is enabled, otherwise =1.
INFO — an INTEGER.
- = 0: successful exit 🌟
- < 0: if INFO = -i, the i-th argument had an illegal value

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

Further Details:

Implemented by Azzam Haidar. King behavior honestly. 👑

okay bestie, we're still in the ✨ Function Documentation ✨ zone and it's giving "citation era" 💅 so let's give credit where credit is due, because these people ate and left no crumbs:

All details are available on technical report, SC11, SC13 papers.

Azzam Haidar, Hatem Ltaief, and Jack Dongarra. Parallel reduction to condensed forms for symmetric eigenvalue problems using aggregated fine-grained and memory-aware kernels. In Proceedings of 2011 International Conference for High Performance Computing, Networking, Storage and Analysis (SC '11), New York, NY, USA, Article 8 , 11 pages. http://doi.acm.org/10.1145/2063384.2063394
A. Haidar, J. Kurzak, P. Luszczek, 2013. An improved parallel singular value algorithm and its implementation for multicore hardware, In Proceedings of 2013 International Conference for High Performance Computing, Networking, Storage and Analysis (SC '13). Denver, Colorado, USA, 2013. Article 90, 12 pages. http://doi.acm.org/10.1145/2503210.2503292
A. Haidar, R. Solca, S. Tomov, T. Schulthess and J. Dongarra. A novel hybrid CPU-GPU generalized eigensolver for electronic structure calculations based on fine-grained memory aware tasks. International Journal of High Performance Computing Applications. Volume 28 Issue 2, Pages 196-209, May 2014. http://hpc.sagepub.com/content/28/2/196

subroutine zhfrk 🦋

subroutine zhfrk (character TRANSR, character UPLO, character TRANS, integer
    N, integer K, double precision ALPHA, complex*16, dimension( lda, * ) A,
    integer LDA, double precision BETA, complex*16, dimension( * ) C)

ZHFRK performs a Hermitian rank-k operation for matrix in RFP format. periodt 💅

Purpose:

Level 3 BLAS like routine for C in RFP Format.

ZHFRK performs one of the Hermitian rank--k operations

   C := alpha*A*A**H + beta*C,

   C := alpha*A**H*A + beta*C,

where alpha and beta are real scalars, C is an n--by--n Hermitian matrix and A is an n--by--k matrix in the first case and a k--by--n matrix in the second case. literally two whole moods of the same routine, pick your fighter ✨

Parameters

TRANSR — TRANSR is CHARACTER*1
- = 'N': The Normal Form of RFP A is stored;
- = 'C': The Conjugate-transpose Form of RFP A is stored.
UPLO — UPLO is CHARACTER*1 On entry, UPLO specifies whether the upper or lower triangular part of the array C is to be referenced as follows:
- UPLO = 'U' or 'u' — Only the upper triangular part of C is to be referenced.
- UPLO = 'L' or 'l' — Only the lower triangular part of C is to be referenced.

Unchanged on exit. (she does not get touched, respect her)

TRANS — TRANS is CHARACTER*1 On entry, TRANS specifies the operation to be performed as follows:
- TRANS = 'N' or 'n' — C := alpha*A*A**H + beta*C.
- TRANS = 'C' or 'c' — C := alpha*A**H*A + beta*C.

Unchanged on exit.

N — N is INTEGER On entry, N specifies the order of the matrix C. N must be at least zero. Unchanged on exit.
K — K is INTEGER On entry with TRANS = 'N' or 'n', K specifies the number of columns of the matrix A, and on entry with TRANS = 'C' or 'c', K specifies the number of rows of the matrix A. K must be at least zero. Unchanged on exit.
ALPHA — ALPHA is DOUBLE PRECISION On entry, ALPHA specifies the scalar alpha. Unchanged on exit.
A — A is COMPLEX*16 array, dimension (LDA,ka) where KA is K when TRANS = 'N' or 'n', and is N otherwise. Before entry with TRANS = 'N' or 'n', the leading N--by--K part of the array A must contain the matrix A, otherwise the leading K--by--N part of the array A must contain the matrix A. Unchanged on exit.
LDA — LDA is INTEGER On entry, LDA specifies the first dimension of A as declared in the calling (sub) program. When TRANS = 'N' or 'n' then LDA must be at least max( 1, n ), otherwise LDA must be at least max( 1, k ). Unchanged on exit.
BETA — BETA is DOUBLE PRECISION On entry, BETA specifies the scalar beta. Unchanged on exit.
C — C is COMPLEX*16 array, dimension (N*(N+1)/2) On entry, the matrix A in RFP Format. RFP Format is described by TRANSR, UPLO and N. Note that the imaginary parts of the diagonal elements need not be set, they are assumed to be zero, and on exit they are set to zero. bestie do NOT rely on your imaginary diagonal surviving, it gets zeroed, that's the deal 🙈

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine zhpcon 🎀

subroutine zhpcon (character UPLO, integer N, complex*16, dimension( * ) AP,
    integer, dimension( * ) IPIV, double precision ANORM, double precision
    RCOND, complex*16, dimension( * ) WORK, integer INFO)

ZHPCON — she checks the vibes of your condition number 💅

Purpose:

ZHPCON estimates the reciprocal of the condition number of a complex Hermitian packed matrix A using the factorization A = U*D*U**H or A = L*D*L**H computed by ZHPTRF.

An estimate is obtained for norm(inv(A)), and the reciprocal of the condition number is computed as RCOND = 1 / (ANORM * norm(inv(A))). math but make it a glow-up check ✨

Parameters

UPLO — UPLO is CHARACTER*1 Specifies whether the details of the factorization are stored as an upper or lower triangular matrix.
- = 'U': Upper triangular, form is A = U*D*U**H;
- = 'L': Lower triangular, form is A = L*D*L**H.
N — N is INTEGER The order of the matrix A. N >= 0.
AP — AP is COMPLEX*16 array, dimension (N*(N+1)/2) The block diagonal matrix D and the multipliers used to obtain the factor U or L as computed by ZHPTRF, stored as a packed triangular matrix.
IPIV — IPIV is INTEGER array, dimension (N) Details of the interchanges and the block structure of D as determined by ZHPTRF.
ANORM — ANORM is DOUBLE PRECISION The 1-norm of the original matrix A.
RCOND — RCOND is DOUBLE PRECISION The reciprocal of the condition number of the matrix A, computed as RCOND = 1/(ANORM * AINVNM), where AINVNM is an estimate of the 1-norm of inv(A) computed in this routine.
WORK — WORK is COMPLEX*16 array, dimension (2*N)
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine zhpgst 🌸

subroutine zhpgst (integer ITYPE, character UPLO, integer N, complex*16,
    dimension( * ) AP, complex*16, dimension( * ) BP, integer INFO)

ZHPGST — glow-up time for your generalized eigenproblem, packed edition 🫶

Purpose:

ZHPGST reduces a complex Hermitian-definite generalized eigenproblem to standard form, using packed storage.

If ITYPE = 1, the problem is A*x = lambda*B*x, and A is overwritten by inv(U**H)*A*inv(U) or inv(L)*A*inv(L**H)

If ITYPE = 2 or 3, the problem is A*B*x = lambda*x or B*A*x = lambda*x, and A is overwritten by U*A*U**H or L**H*A*L.

B must have been previously factorized as U**H*U or L*L**H by ZPPTRF. like, B has to show up already ready, no prepping on the spot okay 🙈

Parameters

ITYPE — ITYPE is INTEGER
- = 1: compute inv(U**H)*A*inv(U) or inv(L)*A*inv(L**H);
- = 2 or 3: compute U*A*U**H or L**H*A*L.
UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored and B is factored as U**H*U;
- = 'L': Lower triangle of A is stored and B is factored as L*L**H.
N — N is INTEGER The order of the matrices A and B. N >= 0.
AP — AP is COMPLEX*16 array, dimension (N*(N+1)/2) On entry, the upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.

On exit, if INFO = 0, the transformed matrix, stored in the same format as A. she comes back different, but the fit is the same 💅

BP — BP is COMPLEX*16 array, dimension (N*(N+1)/2) The triangular factor from the Cholesky factorization of B, stored in the same format as A, as returned by ZPPTRF.
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine zhprfs ⭐

subroutine zhprfs (character UPLO, integer N, integer NRHS, complex*16,
    dimension( * ) AP, complex*16, dimension( * ) AFP, integer, dimension( *
    ) IPIV, complex*16, dimension( ldb, * ) B, integer LDB, complex*16,
    dimension( ldx, * ) X, integer LDX, double precision, dimension( * )
    FERR, double precision, dimension( * ) BERR, complex*16, dimension( * )
    WORK, double precision, dimension( * ) RWORK, integer INFO)

ZHPRFS — the "okay but is my answer actually good" routine 🔥

Purpose:

ZHPRFS improves the computed solution to a system of linear equations when the coefficient matrix is Hermitian indefinite and packed, and provides error bounds and backward error estimates for the solution.

Parameters

UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER The order of the matrix A. N >= 0.
NRHS — NRHS is INTEGER The number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >= 0.
AP —
AP — okay so AP is COMPLEX*16 array, dimension (N*(N+1)/2). It's giving the upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.
AFP — bestie, AFP is COMPLEX*16 array, dimension (N*(N+1)/2). This is the factored form of the matrix A. AFP contains the block diagonal matrix D and the multipliers used to obtain the factor U or L from the factorization A = U*D*U**H or A = L*D*L**H as computed by ZHPTRF, stored as a packed triangular matrix. periodt.
IPIV — IPIV is INTEGER array, dimension (N). It's got the details of the interchanges and the block structure of D as determined by ZHPTRF. iykyk.
B — B is COMPLEX*16 array, dimension (LDB,NRHS). The right hand side matrix B. slay.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
X — X is COMPLEX*16 array, dimension (LDX,NRHS). On entry, the solution matrix X, as computed by ZHPTRS. On exit, the improved solution matrix X. glow-up.
LDX — LDX is INTEGER. The leading dimension of the array X. LDX >= max(1,N).
FERR — FERR is DOUBLE PRECISION array, dimension (NRHS). The estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error. no cap.
BERR — BERR is DOUBLE PRECISION array, dimension (NRHS). The componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution). fr fr.
WORK — WORK is COMPLEX*16 array, dimension (2*N). iconic.
RWORK — RWORK is DOUBLE PRECISION array, dimension (N). main character energy.
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

💖 Internal Parameters 💖

ITMAX is the maximum number of steps of iterative refinement. the way that works is lowkey wild but okay.

👑 Author 👑

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

✨ subroutine zhptrd ✨

   subroutine zhptrd (character UPLO, integer N, complex*16, dimension( * ) AP,
       double precision, dimension( * ) D, double precision, dimension( * ) E,
       complex*16, dimension( * ) TAU, integer INFO)

ZHPTRD

🌸 Purpose 🌸

okay so ZHPTRD reduces a complex Hermitian matrix A stored in packed form to real symmetric tridiagonal form T by a unitary similarity transformation: Q**H * A * Q = T. ate.

🎀 Parameters 🎀

UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
AP — AP is COMPLEX*16 array, dimension (N*(N+1)/2). On entry, the upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n. On exit, if UPLO = 'U', the diagonal and first superdiagonal of A are overwritten by the corresponding elements of the tridiagonal matrix T, and the elements above the first superdiagonal, with the array TAU, represent the unitary matrix Q as a product of elementary reflectors; if UPLO = 'L', the diagonal and first subdiagonal of A are over-written by the corresponding elements of the tridiagonal matrix T, and the elements below the first subdiagonal, with the array TAU, represent the unitary matrix Q as a product of elementary reflectors. See Further Details. the way that AP gets overwritten is giving plot twist.
D — D is DOUBLE PRECISION array, dimension (N). The diagonal elements of the tridiagonal matrix T: D(i) = A(i,i). simple.
E — E is DOUBLE PRECISION array, dimension (N-1). The off-diagonal elements of the tridiagonal matrix T: E(i) = A(i,i+1) if UPLO = 'U', E(i) = A(i+1,i) if UPLO = 'L'.
TAU — TAU is COMPLEX*16 array, dimension (N-1). The scalar factors of the elementary reflectors (see Further Details).
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

👑 Author 👑

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🦋 Further Details 🦋

okay bestie, here's the tea: If UPLO = 'U', the matrix Q is represented as a product of elementary reflectors

                Q = H(n-1) . . . H(2) H(1).

Each H(i) has the form

                H(i) = I - tau * v * v**H

where tau is a complex scalar, and v is a complex vector with v(i+1:n) = 0 and v(i) = 1; v(1:i-1) is stored on exit in AP, overwriting A(1:i-1,i+1), and tau is stored in TAU(i).

If UPLO = 'L', the matrix Q is represented as a product of elementary reflectors

                Q = H(1) H(2) . . . H(n-1).

Each H(i) has the form

                H(i) = I - tau * v * v**H

where tau is a complex scalar, and v is a complex vector with v(1:i) = 0 and v(i+1) = 1; v(i+2:n) is stored on exit in AP, overwriting A(i+2:n,i), and tau is stored in TAU(i). literally the blueprint.

✨ subroutine zhptrf ✨

   subroutine zhptrf (character UPLO, integer N, complex*16, dimension( * ) AP,
       integer, dimension( * ) IPIV, integer INFO)

ZHPTRF

🌸 Purpose 🌸

bestie, ZHPTRF computes the factorization of a complex Hermitian packed matrix A using the Bunch-Kaufman diagonal pivoting method:

      A = U*D*U**H  or  A = L*D*L**H

where U (or L) is a product of permutation and unit upper (lower) triangular matrices, and D is Hermitian and block diagonal with 1-by-1 and 2-by-2 diagonal blocks. slay.

🎀 Parameters 🎀

UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
AP — AP is COMPLEX*16 array, dimension (N*(N+1)/2). On entry, the upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.

On exit, the block diagonal matrix D and the multipliers used to obtain the factor U or L, stored as a packed triangular matrix overwriting A (see below for further details). the way it overwrites is iconic.

IPIV — IPIV is INTEGER array, dimension (N). Details of the interchanges and the block structure of D. If IPIV(k) > 0, then rows and columns k and IPIV(k) were interchanged and D(k,k) is a 1-by-1 diagonal block. If UPLO = 'U' and IPIV(k) = IPIV(k-1) < 0, then rows and columns k-1 and -IPIV(k) were interchanged and D(k-1:k,k-1:k) is a 2-by-2 diagonal block. If UPLO = 'L' and IPIV(k) = IPIV(k+1) < 0, then rows and columns k+1 and -IPIV(k) were interchanged and D(k:k+1,k:k+1) is a 2-by-2 diagonal block. no cap, this is the whole plot.
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, D(i,i) is exactly zero. The factorization has been completed, but the block diagonal matrix D is exactly singular, and division by zero will occur if it is used to solve a system of equations. danger bestie, division by zero is not the vibe.

👑 Author 👑

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🦋 Further Details 🦋

okay so If UPLO = 'U', then A = U*D*U**H, where

                U = P(n)*U(n)* ... *P(k)U(k)* ...,

i.e., U is a product of terms P(k)*U(k), where k decreases from n to 1 in steps of 1 or 2, and D is a block diagonal matrix with 1-by-1 and 2-by-2 diagonal blocks D(k). P(k) is a permutation matrix as defined by IPIV(k), and U(k) is a unit upper triangular matrix, such that if the diagonal block D(k) is of order s (s = 1 or 2), then

                        (   I    v    0   )   k-s
                U(k) =  (   0    I    0   )   s
                        (   0    0    I   )   n-k
                           k-s   s   n-k

If s = 1, D(k) overwrites A(k,k), and v overwrites A(1:k-1,k). If s = 2, the upper triangle of D(k) overwrites A(k-1,k-1), A(k-1,k), and A(k,k), and v overwrites A(1:k-2,k-1:k).

If UPLO = 'L', then A = L*D*L**H, where

                L = P(1)*L(1)* ... *P(k)*L(k)* ...,

i.e., L is a product of terms P(k)*L(k), where k increases from 1 to n in steps of 1 or 2, and D is a block diagonal matrix with 1-by-1 and 2-by-2 diagonal blocks D(k). P(k) is a permutation matrix as defined by IPIV(k), and L(k) is a unit lower triangular matrix, such that if the diagonal block D(k) is of order s (s = 1 or 2), then

                        (   I    0     0   )  k-1
                L(k) =  (   0    I     0   )  s
                        (   0    v     I   )  n-k-s+1
                           k-1   s  n-k-s+1

If s = 1, D(k) overwrites A(k,k), and v overwrites A(k+1:n,k). If s = 2, the lower triangle of D(k) overwrites A(k,k), A(k+1,k), and A(k+1,k+1), and v overwrites A(k+2:n,k:k+1). and that's the whole vibe.

🌟 Contributors 🌟

J. Lewis, Boeing Computer Services Company

✨ `zhptri` / `ZHPTRI` ✨

subroutine zhptri (character UPLO, integer N, complex*16, dimension( * ) AP,
    integer, dimension( * ) IPIV, complex*16, dimension( * ) WORK, integer
    INFO)

okay bestie, this one is giving “undo the factorization” energy. 💅

🎯 Purpose 🎯

ZHPTRI computes the inverse of a complex Hermitian indefinite matrix A in packed storage using the factorization A = U*D*U**H or A = L*D*L**H computed by ZHPTRF.

📋 Parameters 📋

UPLO — UPLO is CHARACTER*1. Specifies whether the details of the factorization are stored as an upper or lower triangular matrix.
- = 'U': Upper triangular, form is A = U*D*U**H;
- = 'L': Lower triangular, form is A = L*D*L**H.
N — N is INTEGER. The order of the matrix A. N >= 0.
AP — AP is COMPLEX*16 array, dimension (N*(N+1)/2). On entry, the block diagonal matrix D and the multipliers used to obtain the factor U or L as computed by ZHPTRF, stored as a packed triangular matrix. On exit, if INFO = 0, the (Hermitian) inverse of the original matrix, stored as a packed triangular matrix. The j-th column of inv(A) is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = inv(A)(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = inv(A)(i,j) for j<=i<=n.
IPIV — IPIV is INTEGER array, dimension (N). Details of the interchanges and the block structure of D as determined by ZHPTRF.
WORK — WORK is COMPLEX*16 array, dimension (N).
INFO — INFO is INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, D(i,i) = 0; the matrix is singular and its inverse could not be computed.

✍️ Author ✍️

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

✨ `zhptrs` / `ZHPTRS` ✨

subroutine zhptrs (character UPLO, integer N, integer NRHS, complex*16,
    dimension( * ) AP, integer, dimension( * ) IPIV, complex*16, dimension(
    ldb, * ) B, integer LDB, integer INFO)

🎯 Purpose 🎯

ZHPTRS solves a system of linear equations A*X = B with a complex Hermitian matrix A stored in packed format using the factorization A = U*D*U**H or A = L*D*L**H computed by ZHPTRF.

📋 Parameters 📋

UPLO — UPLO is CHARACTER*1. Specifies whether the details of the factorization are stored as an upper or lower triangular matrix.
- = 'U': Upper triangular, form is A = U*D*U**H;
- = 'L': Lower triangular, form is A = L*D*L**H.
N — N is INTEGER. The order of the matrix A. N >= 0.
NRHS — NRHS is INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
AP — AP is COMPLEX*16 array, dimension (N*(N+1)/2). The block diagonal matrix D and the multipliers used to obtain the factor U or L as computed by ZHPTRF, stored as a packed triangular matrix.
IPIV — IPIV is INTEGER array, dimension (N). Details of the interchanges and the block structure of D as determined by ZHPTRF.
B — B is COMPLEX*16 array, dimension (LDB,NRHS). On entry, the right hand side matrix B. On exit, the solution matrix X.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
INFO — INFO is INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

✍️ Author ✍️

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

✨ `zhsein` / `ZHSEIN` ✨

subroutine zhsein (character SIDE, character EIGSRC, character INITV,
    logical, dimension( * ) SELECT, integer N, complex*16, dimension( ldh, *
    ) H, integer LDH, complex*16, dimension( * ) W, complex*16, dimension(
    ldvl, * ) VL, integer LDVL, complex*16, dimension( ldvr, * ) VR, integer
    LDVR, integer MM, integer M, complex*16, dimension( * ) WORK, double
    precision, dimension( * ) RWORK, integer, dimension( * ) IFAILL,
    integer, dimension( * ) IFAILR, integer INFO)

🎯 Purpose 🎯

ZHSEIN uses inverse iteration to find specified right and/or left eigenvectors of a complex upper Hessenberg matrix H.

The right eigenvector x and the left eigenvector y of the matrix H corresponding to an eigenvalue w are defined by:

H * x = w * x,     y**h * H = w * y**h

where y**h denotes the conjugate transpose of the vector y.

📋 Parameters 📋

SIDE — SIDE is CHARACTER*1.
- = 'R': compute right eigenvectors only;
- = 'L': compute left eigenvectors only;
- = 'B': compute both right and left eigenvectors.
EIGSRC — EIGSRC is CHARACTER*1. Specifies the source of eigenvalues supplied in W:
- = 'Q': the eigenvalues were found using ZHSEQR; thus, if H has zero subdiagonal elements, and so is block-triangular, then the j-th eigenvalue can be assumed to be an eigenvalue of the block containing the j-th row/column. This property allows ZHSEIN to perform inverse iteration on just one diagonal block.
- = 'N': no assumptions are made on the correspondence between eigenvalues and diagonal blocks. In this case, ZHSEIN must always perform inverse iteration using the whole matrix H.
INITV — INITV is CHARACTER*1.
- = 'N': no initial vectors are supplied;
- = 'U': user-supplied initial vectors are stored in the arrays VL and/or VR.
SELECT — SELECT is LOGICAL array, dimension (N). Specifies the eigenvectors to be computed. To select the eigenvector corresponding to the eigenvalue W(j), SELECT(j) must be set to .TRUE..
N — N is INTEGER. The order of the matrix H. N >= 0.
H — H is COMPLEX*16 array, dimension (LDH,N). The upper Hessenberg matrix H. If a NaN is detected in H, the routine will return with INFO=-6.
LDH — LDH is INTEGER. The leading dimension of the array H. LDH >= max(1,N).
W — W is COMPLEX*16 array, dimension (N). On entry, the eigenvalues of H. On exit, the real parts of W may have been altered since close eigenvalues are perturbed slightly in searching for independent eigenvectors.
VL — VL is COMPLEX*16 array, dimension (LDVL,MM). On entry, if INITV = 'U' and SIDE = 'L' or 'B', VL must contain starting vectors for the inverse iteration for the left eigenvectors; the starting vector for each eigenvector must be in the same column in which the eigenvector will be stored. On exit, if SIDE = 'L' or 'B', the left eigenvectors specified by SELECT will be stored consecutively in the columns of VL, in the same order as their eigenvalues. If SIDE = 'R', VL is not referenced.
LDVL — LDVL is INTEGER. The leading dimension of the array VL. LDVL >= max(1,N) if SIDE = 'L' or 'B'; LDVL >= 1 otherwise.
VR — VR is COMPLEX*16 array, dimension (LDVR,MM). On entry, if INITV = 'U' and SIDE = 'R' or 'B', VR must contain starting vectors for the inverse iteration for the right eigenvectors; the starting vector for each eigenvector must be in the same column in which the eigenvector will be stored. On exit, if SIDE = 'R' or 'B', the right eigenvectors specified by SELECT will be stored consecutively in the columns of VR, in the same order as their eigenvalues. If SIDE = 'L', VR is not referenced.
LDVR — LDVR is INTEGER. The leading dimension of the array VR. LDVR >= max(1,N) if SIDE = 'R' or 'B'; LDVR >= 1 otherwise.
MM — MM is INTEGER. The number of columns in the arrays VL and/or VR. MM >= M.
M — M is INTEGER. The number of columns in the arrays VL and/or VR required to store the eigenvectors (= the number of .TRUE. elements in SELECT).
WORK — WORK is COMPLEX*16 array, dimension (N*N).
RWORK — RWORK is DOUBLE PRECISION array, dimension (N).
IFAILL — IFAILL is INTEGER array, dimension (MM). If SIDE = 'L' or 'B', IFAILL(i) = j > 0 if the left eigenvector in the i-th column of VL (corresponding to the eigenvalue w(j)) failed to converge; IFAILL(i) = 0 if the eigenvector converged satisfactorily. If SIDE = 'R', IFAILL is not referenced.
IFAILR — IFAILR is INTEGER array, dimension (MM). If SIDE = 'R' or 'B', IFAILR(i) = j > 0 if the right eigenvector in the i-th column of VR (corresponding to the eigenvalue w(j)) failed to converge; IFAILR(i) = 0 if the eigenvector converged satisfactorily. If SIDE = 'L', IFAILR is not referenced.
INFO — INFO is INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, i is the number of eigenvectors which failed to converge; see IFAILL and IFAILR for further details.

✍️ Author ✍️

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🔍 Further Details 🔍

Each eigenvector is normalized so that the element of largest magnitude has magnitude 1; here the magnitude of a complex number (x,y) is taken to be |x|+|y|.

✨ `zhseqr` — the Hessenberg eigenvalue slayer ✨

subroutine zhseqr (character JOB, character COMPZ, integer N, integer ILO,
    integer IHI, complex*16, dimension( ldh, * ) H, integer LDH, complex*16,
    dimension( * ) W, complex*16, dimension( ldz, * ) Z, integer LDZ,
    complex*16, dimension( * ) WORK, integer LWORK, integer INFO)

ZHSEQR

✨ Purpose ✨

okay bestie, so ZHSEQR computes the eigenvalues of a Hessenberg matrix H and, optionally, the matrices T and Z from the Schur decomposition H = Z T Z**H, where T is an upper triangular matrix (the Schur form), and Z is the unitary matrix of Schur vectors. 💅

Optionally Z may be postmultiplied into an input unitary matrix Q so that this routine can give the Schur factorization of a matrix A which has been reduced to the Hessenberg form H by the unitary matrix Q: A = Q*H*Q**H = (QZ)*T*(QZ)**H. periodt. ✨

✨ Parameters ✨

JOB — JOB is CHARACTER*1
- = 'E': compute eigenvalues only;
- = 'S': compute eigenvalues and the Schur form T.
COMPZ — COMPZ is CHARACTER*1
- = 'N': no Schur vectors are computed;
- = 'I': Z is initialized to the unit matrix and the matrix Z of Schur vectors of H is returned;
- = 'V': Z must contain an unitary matrix Q on entry, and the product Q*Z is returned.
N — N is INTEGER. The order of the matrix H. N >= 0.
ILO — ILO is INTEGER
IHI — IHI is INTEGER

It is assumed that H is already upper triangular in rows and columns 1:ILO-1 and IHI+1:N. ILO and IHI are normally set by a previous call to ZGEBAL, and then passed to ZGEHRD when the matrix output by ZGEBAL is reduced to Hessenberg form. Otherwise ILO and IHI should be set to 1 and N respectively. If N > 0, then 1 <= ILO <= IHI <= N. If N = 0, then ILO = 1 and IHI = 0.

H — H is COMPLEX*16 array, dimension (LDH,N) On entry, the upper Hessenberg matrix H. On exit, if INFO = 0 and JOB = 'S', H contains the upper triangular matrix T from the Schur decomposition (the Schur form). If INFO = 0 and JOB = 'E', the contents of H are unspecified on exit. (The output value of H when INFO > 0 is given under the description of INFO below.)

Unlike earlier versions of ZHSEQR, this subroutine may explicitly H(i,j) = 0 for i > j and j = 1, 2, ... ILO-1 or j = IHI+1, IHI+2, ... N.

LDH — LDH is INTEGER. The leading dimension of the array H. LDH >= max(1,N).
W — W is COMPLEX*16 array, dimension (N). The computed eigenvalues. If JOB = 'S', the eigenvalues are stored in the same order as on the diagonal of the Schur form returned in H, with W(i) = H(i,i).
Z — Z is COMPLEX*16 array, dimension (LDZ,N) If COMPZ = 'N', Z is not referenced. If COMPZ = 'I', on entry Z need not be set and on exit, if INFO = 0, Z contains the unitary matrix Z of the Schur vectors of H. If COMPZ = 'V', on entry Z must contain an N-by-N matrix Q, which is assumed to be equal to the unit matrix except for the submatrix Z(ILO:IHI,ILO:IHI). On exit, if INFO = 0, Z contains Q*Z. Normally Q is the unitary matrix generated by ZUNGHR after the call to ZGEHRD which formed the Hessenberg matrix H. (The output value of Z when INFO > 0 is given under the description of INFO below.)
LDZ — LDZ is INTEGER. The leading dimension of the array Z. if COMPZ = 'I' or COMPZ = 'V', then LDZ >= MAX(1,N). Otherwise, LDZ >= 1.
WORK — WORK is COMPLEX*16 array, dimension (LWORK). On exit, if INFO = 0, WORK(1) returns an estimate of the optimal value for LWORK.
LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= max(1,N) is sufficient and delivers very good and sometimes optimal performance. However, LWORK as large as 11*N may be required for optimal performance. A workspace query is recommended to determine the optimal workspace size.

If LWORK = -1, then ZHSEQR does a workspace query. In this case, ZHSEQR checks the input parameters and estimates the optimal workspace size for the given values of N, ILO and IHI. The estimate is returned in WORK(1). No error message related to LWORK is issued by XERBLA. Neither H nor Z are accessed.

INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, ZHSEQR failed to compute all of the eigenvalues. Elements 1:ilo-1 and i+1:n of W contain those eigenvalues which have been successfully computed. (Failures are rare.)

If INFO > 0 and JOB = 'E', then on exit, the remaining unconverged eigenvalues are the eigenvalues of the upper Hessenberg matrix rows and columns ILO through INFO of the final, output value of H.

If INFO > 0 and JOB = 'S', then on exit

(*)  (initial value of H)*U  = U*(final value of H)

where U is a unitary matrix. The final value of H is upper Hessenberg and triangular in rows and columns INFO+1 through IHI.

If INFO > 0 and COMPZ = 'V', then on exit

(final value of Z)  =  (initial value of Z)*U

where U is the unitary matrix in (*) (regardless of the value of JOB.)

If INFO > 0 and COMPZ = 'I', then on exit

(final value of Z)  = U

where U is the unitary matrix in (*) (regardless of the value of JOB.)

If INFO > 0 and COMPZ = 'N', then Z is not accessed.

✨ Author ✨

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

✨ Contributors ✨

Karen Braman and Ralph Byers, Department of Mathematics, University of Kansas, USA

✨ Further Details ✨

Default values supplied by ILAENV(ISPEC,'ZHSEQR',JOB(:1)//COMPZ(:1),N,ILO,IHI,LWORK). It is suggested that these defaults be adjusted in order to attain best performance in each particular computational environment.

ISPEC=12: The ZLAHQR vs ZLAQR0 crossover point. Default: 75. (Must be at least 11.)
ISPEC=13: Recommended deflation window size. This depends on ILO, IHI and NS. NS is the number of simultaneous shifts returned by ILAENV(ISPEC=15). (See ISPEC=15 below.) The default for (IHI-ILO+1) <= 500 is NS. The default for (IHI-ILO+1) > 500 is 3*NS/2.
ISPEC=14: Nibble crossover point. (See IPARMQ for details.) Default: 14% of deflation window size.
ISPEC=15: Number of simultaneous shifts in a multishift QR iteration.

If IHI-ILO+1 is ...

greater than      ...but less    ... the
or equal to ...      than        default is

     1               30          NS =   2(+)
    30               60          NS =   4(+)
    60              150          NS =  10(+)
   150              590          NS =  **
   590             3000          NS =  64
  3000             6000          NS = 128
  6000             infinity      NS = 256

(+) By default some or all matrices of this order are passed to the implicit double shift routine ZLAHQR and this parameter is ignored. See ISPEC=12 above and comments in IPARMQ for details.

(**) The asterisks (**) indicate an ad-hoc function of N increasing from 10 to 64.

ISPEC=16: Select structured matrix multiply. If the number of simultaneous shifts (specified by ISPEC=15) is less than 14, then the default for ISPEC=16 is 0. Otherwise the default for ISPEC=16 is 2.

✨ References ✨

K. Braman, R. Byers and R. Mathias, The Multi-Shift QR Algorithm Part I: Maintaining Well Focused Shifts, and Level 3 Performance, SIAM Journal of Matrix Analysis, volume 23, pages 929--947, 2002.
K. Braman, R. Byers and R. Mathias, The Multi-Shift QR Algorithm Part II: Aggressive Early Deflation, SIAM Journal of Matrix Analysis, volume 23, pages 948--973, 2002.

✨ `zla_lin_berr` — component-wise relative backward error ✨

subroutine zla_lin_berr (integer N, integer NZ, integer NRHS, complex*16,
    dimension( n, nrhs ) RES, double precision, dimension( n, nrhs ) AYB,
    double precision, dimension( nrhs ) BERR)

ZLA_LIN_BERR computes a component-wise relative backward error.

✨ Purpose ✨

ZLA_LIN_BERR computes componentwise relative backward error from the formula

max(i) ( abs(R(i)) / ( abs(op(A_s))*abs(Y) + abs(B_s) )(i) )

where abs(Z) is the componentwise absolute value of the matrix or vector Z.

✨ Parameters ✨

N — N is INTEGER. The number of linear equations, i.e., the order of the matrix A. N >= 0.
NZ
NZ — INTEGER. bestie listen, we add (NZ+1)*SLAMCH( 'Safe minimum' ) to R(i) in the numerator so we don't get clowned by spuriously zero residuals 🙈 default value is N.
NRHS — INTEGER. the number of right hand sides, aka the number of columns of the matrices AYB, RES, and BERR. NRHS >= 0.
RES — *COMPLEX*16 array, dimension (N,NRHS). the residual matrix, i.e. the matrix R in the relative backward error formula above. iconic.
AYB — DOUBLE PRECISION array, dimension (N, NRHS). the denominator in the relative backward error formula above, i.e. the matrix abs(op(A_s))*abs(Y) + abs(B_s). The matrices A, Y, and B are from iterative refinement (see zla_gerfsx_extended.f) 👑
BERR — DOUBLE PRECISION array, dimension (NRHS). the componentwise relative backward error from the formula above. slay.

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

`subroutine zla_wwaddw` (`integer N, complex16, dimension( ) X, complex16, dimension( ) Y, complex16, dimension( ) W`)

ZLA_WWADDW adds a vector into a doubled-single vector. ok that's the whole vibe ✨

Purpose:

ZLA_WWADDW adds a vector W into a doubled-single vector (X, Y).

This works for all extant IBM's hex and binary floating point
arithmetic, but not for decimal.

not for decimal, bestie. hex and binary only, that's the rule 💅

Parameters

N — INTEGER. the length of vectors X, Y, and W.
X — *COMPLEX*16 array, dimension (N). the first part of the doubled-single accumulation vector.
Y — *COMPLEX*16 array, dimension (N). the second part of the doubled-single accumulation vector.
W — *COMPLEX*16 array, dimension (N). the vector to be added.

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

`subroutine zlaed0` (`integer QSIZ, integer N, double precision, dimension( * ) D, double precision, dimension( * ) E, complex16, dimension( ldq, ) Q, integer LDQ, complex16, dimension( ldqs, ) QSTORE, integer LDQS, double precision, dimension( * ) RWORK, integer, dimension( * ) IWORK, integer INFO`)

ZLAED0 used by ZSTEDC. Computes all eigenvalues and corresponding eigenvectors of an unreduced symmetric tridiagonal matrix using the divide and conquer method. divide and conquer but make it math 💖

Purpose:

Using the divide and conquer method, ZLAED0 computes all eigenvalues
of a symmetric tridiagonal matrix which is one diagonal block of
those from reducing a dense or band Hermitian matrix and
corresponding eigenvectors of the dense or band matrix.

Parameters

QSIZ — INTEGER. the dimension of the unitary matrix used to reduce the full matrix to tridiagonal form. QSIZ >= N if ICOMPQ = 1.
N — INTEGER. the dimension of the symmetric tridiagonal matrix. N >= 0.
D — DOUBLE PRECISION array, dimension (N). on entry, the diagonal elements of the tridiagonal matrix. On exit, the eigenvalues in ascending order. sorted, periodt 🎀
E — DOUBLE PRECISION array, dimension (N-1). on entry, the off-diagonal elements of the tridiagonal matrix. On exit, E has been destroyed. 💀 yeah she's gone
Q — COMPLEX16 array, dimension (LDQ,N)*. on entry, Q must contain an QSIZ x N matrix whose columns unitarily orthonormal. It is a part of the unitary matrix that reduces the full dense Hermitian matrix to a (reducible) symmetric tridiagonal matrix.
LDQ — INTEGER. the leading dimension of the array Q. LDQ >= max(1,N).
IWORK — INTEGER array, the dimension of IWORK must be at least

6 + 6*N + 5*N*lg N
( lg( N ) = smallest integer k
            such that 2^k >= N )

RWORK — DOUBLE PRECISION array, dimension (1 + 3*N + 2*N*lg N + 3*N**2)

( lg( N ) = smallest integer k
            such that 2^k >= N )

QSTORE — COMPLEX16 array, dimension (LDQS, N)*. used to store parts of the eigenvector matrix when the updating matrix multiplies take place.
LDQS — INTEGER. the leading dimension of the array QSTORE. LDQS >= max(1,N).
INFO — INTEGER.
- = 0: successful exit. we love to see it ✨
- < 0: if INFO = -i, the i-th argument had an illegal value.
- > 0: the algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and columns INFO/(N+1) through mod(INFO,N+1). not the vibe 😭

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

`subroutine zlaed7` (integer N, integer CUTPNT, integer QSIZ, integer TLVLS, integer CURLVL, integer CURPBM, double precision, dimension( * ) D, complex16, dimension( ldq, ) Q, integer LDQ, double precision RHO, integer, dimension( * ) INDXQ, double precision, dimension( * ) QSTORE, integer, dimension( * ) QPTR, integer, dimension( * ) PRMPTR, integer, dimension( * ) PERM, integer, dimension( * ) GIVPTR, integer, dimension( 2, * ) GIVCOL, double precision, dimension( 2, * ) GIVNUM, complex16, dimension( ) WORK, double precision, dimension( * ) RWORK, integer, dimension( * ) IWORK, integer INFO)

ZLAED7 used by ZSTEDC. Computes the updated eigensystem of a diagonal matrix after modification by a rank-one symmetric matrix. Used when the original matrix is dense. rank-one glow-up incoming 🌸

Purpose:

ZLAED7 computes the updated eigensystem of a diagonal
matrix after modification by a rank-one symmetric matrix. This
routine is used only for the eigenproblem which requires all
eigenvalues and optionally eigenvectors of a dense or banded
Hermitian matrix that has been reduced to tridiagonal form.

  T = Q(in) ( D(in) + RHO * Z*Z**H ) Q**H(in) = Q(out) * D(out) * Q**H(out)

  where Z = Q**Hu, u is a vector of length N with ones in the
  CUTPNT and CUTPNT + 1 th elements and zeros elsewhere.

and then the algorithm is a whole three-act structure, no notes:

   The eigenvectors of the original matrix are stored in Q, and the
   eigenvalues are in D.  The algorithm consists of three stages:

      The first stage consists of deflating the size of the problem
      when there are multiple eigenvalues or if there is a zero in
      the Z vector.  For each such occurrence the dimension of the
      secular equation problem is reduced by one.  This stage is
      performed by the routine DLAED2.

      The second stage consists of calculating the updated
      eigenvalues. This is done by finding the roots of the secular
      equation via the routine DLAED4 (as called by SLAED3).
      This routine also calculates the eigenvectors of the current
      problem.

      The final stage consists of computing the updated eigenvectors
      directly using the updated eigenvalues.  The eigenvectors for
      the current problem are multiplied with the eigenvectors from
      the overall problem.

three stages, three routines, one slay 💅 DLAED2 does the deflating, DLAED4 (called by SLAED3) finds the roots of the secular equation, and the finale computes the updated eigenvectors directly.

Parameters

N — INTEGER. the dimension of the symmetric tridiagonal matrix. N >= 0.
CUTPNT — INTEGER. contains the location of the last eigenvalue in the leading sub-matrix. min(1,N) <= CUTPNT <= N.
QSIZ — INTEGER. the dimension of the unitary matrix used to reduce the full matrix to tridiagonal form. QSIZ >= N.
TLVLS — INTEGER. the total number of merging levels in the overall divide and conquer tree. 🌳
CURLVL — INTEGER. the current level in the overall merge routine, 0 <= curlvl <= tlvls.
CURPBM — INTEGER. the current problem in the current level in the overall merge routine (counting from upper left to lower right).
D — DOUBLE PRECISION array, dimension (N). on entry, the eigenvalues of the rank-1-perturbed matrix. On exit, the eigenvalues of the repaired matrix. she's healed ✨
Q — COMPLEX16 array, dimension (LDQ,N)*. on entry, the eigenvectors of the rank-1-perturbed matrix. On exit, the eigenvectors of the repaired tridiagonal matrix.
LDQ — INTEGER. the leading dimension of the array Q. LDQ >= max(1,N).
RHO — DOUBLE PRECISION. contains the subdiagonal element used to create the rank-1 modification.
INDXQ — INTEGER array, dimension (N). this contains the permutation which will reintegrate the subproblem just solved back into sorted order, ie. D( INDXQ( I = 1, N ) ) will be in ascending order.
IWORK — INTEGER array, dimension (4*N).
RWORK — DOUBLE PRECISION array, dimension (3*N+2*QSIZ*N).
WORK — COMPLEX16 array, dimension (QSIZ*N)*.
QSTORE — DOUBLE PRECISION array, dimension (N**2+1). stores eigenvectors of submatrices encountered during divide and conquer, packed together. QPTR points to beginning of the submatrices.
QPTR — INTEGER array, dimension (N+2). list of indices pointing to beginning of submatrices stored in QSTORE. The submatrices are numbered starting at the bottom left of the divide and conquer tree, from left to right and bottom to top.
PRMPTR
PRMPTR — PRMPTR is INTEGER array, dimension (N lg N). Think of it as the lil map 🗺️ that says where in PERM a level's permutation is stored. And here's the tea: PRMPTR(i+1) - PRMPTR(i) tells you the size of the permutation and the size of the full, non-deflated problem. two facts, one subtraction, we love efficiency ✨
PERM — PERM is INTEGER array, dimension (N lg N). It holds the permutations (from deflation and sorting) that get applied to each eigenblock. queen of reordering 👑
GIVPTR — GIVPTR is INTEGER array, dimension (N lg N). Pointers saying where in GIVCOL a level's Givens rotations are chillin'. GIVPTR(i+1) - GIVPTR(i) = the number of Givens rotations. counting queen 💅
GIVCOL — GIVCOL is INTEGER array, dimension (2, N lg N). Every pair of numbers = a pair of columns that are gonna take place in a Givens rotation.
GIVNUM — GIVNUM is DOUBLE PRECISION array, dimension (2, N lg N). Each number = the S value to be used in the matching Givens rotation.
INFO — INFO is INTEGER
- = 0: successful exit. we ate, no crumbs 😌
- < 0: if INFO = -i, the i-th argument had an illegal value 😭
- > 0: if INFO = 1, an eigenvalue did not converge 💀

Author 💖

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine `zlaed8` 🦋

subroutine zlaed8 (integer K, integer N, integer QSIZ, complex*16, dimension( ldq, * ) Q, integer LDQ, double precision, dimension( * ) D, double precision RHO, integer CUTPNT, double precision, dimension( * ) Z, double precision, dimension( * ) DLAMDA, complex*16, dimension( ldq2, * ) Q2, integer LDQ2, double precision, dimension( * ) W, integer, dimension( * ) INDXP, integer, dimension( * ) INDX, integer, dimension( * ) INDXQ, integer, dimension( * ) PERM, integer GIVPTR, integer, dimension( 2, * ) GIVCOL, double precision, dimension( 2, * ) GIVNUM, integer INFO)

ZLAED8 used by ZSTEDC. Merges eigenvalues and deflates secular equation. Used when the original matrix is dense.

Purpose ✨

ZLAED8 merges the two sets of eigenvalues together into a single sorted set. Then it tries to deflate the size of the problem. There are two ways deflation can happen: when two or more eigenvalues are close together, or if there's a tiny element in the Z vector. For each such occurrence the order of the related secular equation problem gets reduced by one. tiny element found → problem got smaller, periodt 💅

Parameters 🎀

K — K is INTEGER. Holds the number of non-deflated eigenvalues. This is the order of the related secular equation.
N — N is INTEGER. The dimension of the symmetric tridiagonal matrix. N >= 0.
QSIZ — QSIZ is INTEGER. The dimension of the unitary matrix used to reduce the dense or band matrix to tridiagonal form. QSIZ >= N if ICOMPQ = 1.
Q — Q is COMPLEX*16 array, dimension (LDQ,N). On entry, Q contains the eigenvectors of the partially solved system which has been previously updated in matrix multiplies with other partially solved eigensystems. On exit, Q contains the trailing (N-K) updated eigenvectors (those which were deflated) in its last N-K columns.
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= max( 1, N ).
D — D is DOUBLE PRECISION array, dimension (N). On entry, D contains the eigenvalues of the two submatrices to be combined. On exit, D contains the trailing (N-K) updated eigenvalues (those which were deflated) sorted into increasing order.
RHO — RHO is DOUBLE PRECISION. Contains the off diagonal element associated with the rank-1 cut which originally split the two submatrices which are now being recombined. RHO is modified during the computation to the value required by DLAED3. glow-up in real time ✨
CUTPNT — CUTPNT is INTEGER. Contains the location of the last eigenvalue in the leading sub-matrix. MIN(1,N) <= CUTPNT <= N.
Z — Z is DOUBLE PRECISION array, dimension (N). On input this vector contains the updating vector (the last row of the first sub-eigenvector matrix and the first row of the second sub-eigenvector matrix). The contents of Z are destroyed during the updating process. rip to Z's contents, gone but not forgotten 😭
DLAMDA — DLAMDA is DOUBLE PRECISION array, dimension (N). Contains a copy of the first K eigenvalues which will be used by DLAED3 to form the secular equation.
Q2 — Q2 is COMPLEX*16 array, dimension (LDQ2,N). If ICOMPQ = 0, Q2 is not referenced. Otherwise, contains a copy of the first K eigenvectors which will be used by DLAED7 in a matrix multiply (DGEMM) to update the new eigenvectors.
LDQ2 — LDQ2 is INTEGER. The leading dimension of the array Q2. LDQ2 >= max( 1, N ).
W — W is DOUBLE PRECISION array, dimension (N). This will hold the first k values of the final deflation-altered z-vector and will be passed to DLAED3.
INDXP — INDXP is INTEGER array, dimension (N). This will contain the permutation used to place deflated values of D at the end of the array. On output INDXP(1:K) points to the nondeflated D-values and INDXP(K+1:N) points to the deflated eigenvalues. sorting the keepers from the deflated, iconic 🫶
INDX — INDX is INTEGER array, dimension (N). This will contain the permutation used to sort the contents of D into ascending order.
INDXQ — INDXQ is INTEGER array, dimension (N). This contains the permutation which separately sorts the two sub-problems in D into ascending order. Note that elements in the second half of this permutation must first have CUTPNT added to their values in order to be accurate. don't forget that lil CUTPNT add, bestie, or the numbers are lying 🙈
PERM — PERM is INTEGER array, dimension (N). Contains the permutations (from deflation and sorting) to be applied to each eigenblock.
GIVPTR — GIVPTR is INTEGER. Contains the number of Givens rotations which took place in this subproblem.
GIVCOL — GIVCOL is INTEGER array, dimension (2, N). Each pair of numbers indicates a pair of columns to take place in a Givens rotation.
GIVNUM — GIVNUM is DOUBLE PRECISION array, dimension (2, N). Each number indicates the S value to be used in the corresponding Givens rotation.
INFO — INFO is INTEGER
- = 0: successful exit.
- < 0: if INFO = -i, the i-th argument had an illegal value.

Author 💜

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine `zlals0` 🌸

subroutine zlals0 (integer ICOMPQ, integer NL, integer NR, integer SQRE, integer NRHS, complex*16, dimension( ldb, * ) B, integer LDB, complex*16, dimension( ldbx, * ) BX, integer LDBX, integer, dimension( * ) PERM, integer GIVPTR, integer, dimension( ldgcol, * ) GIVCOL, integer LDGCOL, double precision, dimension( ldgnum, * ) GIVNUM, integer LDGNUM, double precision, dimension( ldgnum, * ) POLES, double precision, dimension( * ) DIFL, double precision, dimension( ldgnum, * ) DIFR, double precision, dimension( * ) Z, integer K, double precision C, double precision S, double precision, dimension( * ) RWORK, integer INFO)

ZLALS0 applies back multiplying factors in solving the least squares problem using divide and conquer SVD approach. Used by sgelsd.

Purpose ⭐

ZLALS0 applies back the multiplying factors of either the left or the right singular vector matrix of a diagonal matrix appended by a row to the right hand side matrix B in solving the least squares problem using the divide-and-conquer SVD approach.

For the left singular vector matrix, three types of orthogonal matrices are involved:

(1L) Givens rotations: the number of such rotations is GIVPTR; the pairs of columns/rows they were applied to are stored in GIVCOL; and the C- and S-values of these rotations are stored in GIVNUM.
(2L) Permutation. The (NL+1)-st row of B is to be moved to the first row, and for J=2:N, PERM(J)-th row of B is to be moved to the J-th row.
(3L) The left singular vector matrix of the remaining matrix.

For the right singular vector matrix, four types of orthogonal matrices are involved:

(1R) The right singular vector matrix of the remaining matrix.
(2R) If SQRE = 1, one extra Givens rotation to generate the right null space.
(3R) The inverse transformation of (2L).
(4R) The inverse transformation of (1L).

Parameters 🧚

ICOMPQ — ICOMPQ is INTEGER. Specifies whether singular vectors are to be computed in factored form:
- = 0: Left singular vector matrix.
- = 1: Right singular vector matrix.
NL — NL is INTEGER. The row dimension of the upper block. NL >= 1.
NR — NR is INTEGER. The row dimension of the lower block. NR >= 1.
SQRE — SQRE is INTEGER.
- = 0: the lower block is an NR-by-NR square matrix.
- = 1: the lower block is an NR-by-(NR+1) rectangular matrix.

The bidiagonal matrix has row dimension N = NL + NR + 1, and column dimension M = N + SQRE.

NRHS — NRHS is INTEGER. The number of columns of B and BX. NRHS must be at least 1.
B — B is COMPLEX*16 array, dimension ( LDB, NRHS ). On input, B contains the right hand sides of the least squares problem in rows 1 through M. On output, B contains the solution X in rows 1 through N. glow-up from problem to solution 💖
LDB —
LDB — she's an INTEGER, and she's the leading dimension of B. The rule, no cap: LDB must be at least max(1,MAX( M, N )). Respect the boundary, bestie. 💅
BX — a COMPLEX*16 array, dimension ( LDBX, NRHS ). There she is. ✨
LDBX — INTEGER. The leading dimension of BX. That's the whole assignment, and she ate. 🎀
PERM — INTEGER array, dimension ( N ). It's holding the permutations (from deflation and sorting, iykyk) that got applied to the two blocks.
GIVPTR — INTEGER. The number of Givens rotations that took place in this subproblem. She's literally keeping count. 🔥
GIVCOL — INTEGER array, dimension ( LDGCOL, 2 ). Each pair of numbers indicates a pair of rows/columns involved in a Givens rotation.
LDGCOL — INTEGER. The leading dimension of GIVCOL, and it must be at least N. Firm boundaries, iconic behavior. 👑
GIVNUM — DOUBLE PRECISION array, dimension ( LDGNUM, 2 ). Each number indicates the C or S value used in the corresponding Givens rotation.
LDGNUM — INTEGER. The leading dimension of arrays DIFR, POLES and GIVNUM, and it must be at least K. ✨
POLES — DOUBLE PRECISION array, dimension ( LDGNUM, 2 ). On entry, POLES(1:K, 1) contains the new singular values obtained from solving the secular equation, and POLES(1:K, 2) is an array containing the poles in the secular equation.
DIFL — DOUBLE PRECISION array, dimension ( K ). On entry, DIFL(I) is the distance between the I-th updated (undeflated) singular value and the I-th (undeflated) old singular value.
DIFR — DOUBLE PRECISION array, dimension ( LDGNUM, 2 ). On entry, DIFR(I, 1) contains the distances between the I-th updated (undeflated) singular value and the I+1-th (undeflated) old singular value. And DIFR(I, 2) is the normalizing factor for the I-th right singular vector. 🦋
Z — DOUBLE PRECISION array, dimension ( K ). Contains the components of the deflation-adjusted updating row vector.
K — INTEGER. Contains the dimension of the non-deflated matrix. This is the order of the related secular equation. And the vibe check is 1 <= K <=N. 💜
C — DOUBLE PRECISION. Heads up: C contains garbage if SQRE =0, and the C-value of a Givens rotation related to the right null space if SQRE = 1.
S — DOUBLE PRECISION. Same energy: S contains garbage if SQRE =0, and the S-value of a Givens rotation related to the right null space if SQRE = 1.
RWORK — DOUBLE PRECISION array, dimension ( K*(1+NRHS) + 2*NRHS ).
INFO — INTEGER. The tea, served fresh:
- = 0: successful exit. 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. 💀

👑 Author 👑

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🫶 Contributors 🫶

Ming Gu and Ren-Cang Li, Computer Science Division, University of California at Berkeley, USA
Osni Marques, LBNL/NERSC, USA

🦋 subroutine zlalsa 🦋

subroutine zlalsa (integer ICOMPQ, integer SMLSIZ, integer N, integer NRHS,
    complex*16, dimension( ldb, * ) B, integer LDB, complex*16, dimension(
    ldbx, * ) BX, integer LDBX, double precision, dimension( ldu, * ) U,
    integer LDU, double precision, dimension( ldu, * ) VT, integer,
    dimension( * ) K, double precision, dimension( ldu, * ) DIFL, double
    precision, dimension( ldu, * ) DIFR, double precision, dimension( ldu, *
    ) Z, double precision, dimension( ldu, * ) POLES, integer, dimension( *
    ) GIVPTR, integer, dimension( ldgcol, * ) GIVCOL, integer LDGCOL,
    integer, dimension( ldgcol, * ) PERM, double precision, dimension( ldu,
    * ) GIVNUM, double precision, dimension( * ) C, double precision,
    dimension( * ) S, double precision, dimension( * ) RWORK, integer,
    dimension( * ) IWORK, integer INFO)
    ZLALSA computes the SVD of the coefficient matrix in compact form. Used
    by sgelsd.

So basically ZLALSA computes the SVD of the coefficient matrix in compact form, and sgelsd is the one sliding into her DMs. 💅

Purpose

ZLALSA is an itermediate step in solving the least squares problem by computing the SVD of the coefficient matrix in compact form (the singular vectors are computed as products of simple orthorgonal matrices, iconic).

If ICOMPQ = 0, ZLALSA applies the inverse of the left singular vector matrix of an upper bidiagonal matrix to the right hand side; and if ICOMPQ = 1, ZLALSA applies the right singular vector matrix to the right hand side. The singular vector matrices were generated in compact form by ZLALSA. She's self-made, periodt. ✨

Parameters

ICOMPQ — INTEGER. Specifies whether the left or the right singular vector matrix is involved.
- = 0: Left singular vector matrix
- = 1: Right singular vector matrix
SMLSIZ — INTEGER. The maximum size of the subproblems at the bottom of the computation tree. 🌸
N — INTEGER. The row and column dimensions of the upper bidiagonal matrix.
NRHS — INTEGER. The number of columns of B and BX. And NRHS must be at least 1. No zero, bestie. 🎀
B — COMPLEX*16 array, dimension ( LDB, NRHS ). On input, B contains the right hand sides of the least squares problem in rows 1 through M. On output, B contains the solution X in rows 1 through N.
LDB — INTEGER. The leading dimension of B in the calling subprogram. LDB must be at least max(1,MAX( M, N ) ). 💅
BX — COMPLEX*16 array, dimension ( LDBX, NRHS ). On exit, the result of applying the left or right singular vector matrix to B.
LDBX — INTEGER. The leading dimension of BX. ✨
U — DOUBLE PRECISION array, dimension ( LDU, SMLSIZ ). On entry, U contains the left singular vector matrices of all subproblems at the bottom level.
LDU — INTEGER, LDU = > N. The leading dimension of arrays U, VT, DIFL, DIFR, POLES, GIVNUM, and Z. She's holding so many arrays together, main character energy. 👑
VT — DOUBLE PRECISION array, dimension ( LDU, SMLSIZ+1 ). On entry, VT**H contains the right singular vector matrices of all subproblems at the bottom level.
K — INTEGER array, dimension ( N ).
DIFL — DOUBLE PRECISION array, dimension ( LDU, NLVL ). where NLVL = INT(log_2 (N/(SMLSIZ+1))) + 1.
DIFR — DOUBLE PRECISION array, dimension ( LDU, 2 * NLVL ). On entry, DIFL(*, I) and DIFR(*, 2 * I -1) record distances between singular values on the I-th level and singular values on the (I -1)-th level, and DIFR(*, 2 * I) record the normalizing factors of the right singular vectors matrices of subproblems on I-th level. 🦋
Z — DOUBLE PRECISION array, dimension ( LDU, NLVL ). On entry, Z(1, I) contains the components of the deflation-adjusted updating row vector for subproblems on the I-th level.
POLES — DOUBLE PRECISION array, dimension ( LDU, 2 * NLVL ). On entry, POLES(*, 2 * I -1: 2 * I) contains the new and old singular values involved in the secular equations on the I-th level.
GIVPTR — INTEGER array, dimension ( N ). On entry, GIVPTR( I ) records the number of Givens rotations performed on the I-th problem on the computation tree. 🔥
GIVCOL — INTEGER array, dimension ( LDGCOL, 2 * NLVL ). On entry, for each I, GIVCOL(*, 2 * I - 1: 2 * I) records the locations of Givens rotations performed on the I-th level on the computation tree.
LDGCOL — INTEGER, LDGCOL = > N. The leading dimension of arrays GIVCOL and PERM.
PERM — INTEGER array, dimension ( LDGCOL, NLVL ). On entry, PERM(*, I) records permutations done on the I-th level of the computation tree.
GIVNUM — DOUBLE PRECISION array, dimension ( LDU, 2 * NLVL ). On entry, GIVNUM(*, 2 *I -1 : 2 * I) records the C- and S-values of Givens rotations performed on the I-th level on the computation tree.
C — DOUBLE PRECISION array, dimension ( N ). On entry, if the I-th subproblem is not square, C( I ) contains the C-value of a Givens rotation related to the right null space of the I-th subproblem.
S — DOUBLE PRECISION array, dimension ( N ). On entry, if the I-th subproblem is not square, S( I ) contains the S-value of a Givens rotation related to the right null space of the I-th subproblem.
RWORK — DOUBLE PRECISION array, dimension at least MAX( (SMLSZ+1)*NRHS*3, N*(1+NRHS) + 2*NRHS ).
IWORK — INTEGER array, dimension (3*N)
INFO — INTEGER. The recap, one more time:
- = 0: successful exit. 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. 💀

👑 Author 👑

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🫶 Contributors 🫶

Ming Gu and Ren-Cang Li, Computer Science Division, University of California at Berkeley, USA
Osni Marques, LBNL/NERSC, USA

🌈 subroutine zlalsd 🌈

subroutine zlalsd (character UPLO, integer SMLSIZ, integer N, integer NRHS,
    double precision, dimension( * ) D, double precision, dimension( * ) E,
    complex*16, dimension( ldb, * ) B, integer LDB, double precision RCOND,
    integer RANK, complex*16, dimension( * ) WORK, double precision,
    dimension( * ) RWORK, integer, dimension( * ) IWORK, integer INFO)
    ZLALSD uses the singular value decomposition of A to solve the least
    squares problem.

ZLALSD uses the singular value decomposition of A to solve the least squares problem. She's giving solver, she's giving decomposition, she's everything. ✨

Purpose 💖

Okay bestie, so ZLALSD is out here using the singular value decomposition of A to solve the least squares problem — we're finding X to minimize the Euclidean norm of each column of A*X-B, where A is N-by-N upper bidiagonal, and X and B are N-by-NRHS. And the solution X just overwrites B. Iconic behavior.

The singular values of A smaller than RCOND times the largest singular value are treated as zero in solving the least squares problem; in this case a minimum norm solution is returned. The actual singular values are returned in D in ascending order.

This code makes very mild assumptions about floating point arithmetic. It will work on machines with a guard digit in add/subtract, or on those binary machines without guard digits which subtract like the Cray XMP, Cray YMP, Cray C 90, or Cray 2. It could conceivably fail on hexadecimal or decimal machines without guard digits, but we know of none. No cap.

Parameters 🎀

UPLO — UPLO is CHARACTER*1
- = 'U': D and E define an upper bidiagonal matrix.
- = 'L': D and E define a lower bidiagonal matrix.
SMLSIZ — SMLSIZ is INTEGER. The maximum size of the subproblems at the bottom of the computation tree.
N — N is INTEGER. The dimension of the bidiagonal matrix. N >= 0.
NRHS — NRHS is INTEGER. The number of columns of B. NRHS must be at least 1.
D — D is DOUBLE PRECISION array, dimension (N). On entry D contains the main diagonal of the bidiagonal matrix. On exit, if INFO = 0, D contains its singular values.
E — E is DOUBLE PRECISION array, dimension (N-1). Contains the super-diagonal entries of the bidiagonal matrix. On exit, E has been destroyed. Gone. Reduced to atoms.
B — B is COMPLEX*16 array, dimension (LDB,NRHS). On input, B contains the right hand sides of the least squares problem. On output, B contains the solution X.
LDB — LDB is INTEGER. The leading dimension of B in the calling subprogram. LDB must be at least max(1,N).
RCOND — RCOND is DOUBLE PRECISION. The singular values of A less than or equal to RCOND times the largest singular value are treated as zero in solving the least squares problem. If RCOND is negative, machine precision is used instead. For example, if diag(S)*X=B were the least squares problem, where diag(S) is a diagonal matrix of singular values, the solution would be X(i) = B(i) / S(i) if S(i) is greater than RCOND*max(S), and X(i) = 0 if S(i) is less than or equal to RCOND*max(S).
RANK — RANK is INTEGER. The number of singular values of A greater than RCOND times the largest singular value.
WORK — WORK is COMPLEX*16 array, dimension (N * NRHS).
RWORK — RWORK is DOUBLE PRECISION array, dimension at least

                  (9*N + 2*N*SMLSIZ + 8*N*NLVL + 3*SMLSIZ*NRHS +
                  MAX( (SMLSIZ+1)**2, N*(1+NRHS) + 2*NRHS ),
                  where
                  NLVL = MAX( 0, INT( LOG_2( MIN( M,N )/(SMLSIZ+1) ) ) + 1 )

IWORK — IWORK is INTEGER array, dimension at least (3*N*NLVL + 11*N).
INFO — INFO is INTEGER
- = 0: successful exit.
- < 0: if INFO = -i, the i-th argument had an illegal value.
- > 0: The algorithm failed to compute a singular value while working on the submatrix lying in rows and columns INFO/(N+1) through MOD(INFO,N+1).

Author 🫶

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

Contributors 💜

Ming Gu and Ren-Cang Li, Computer Science Division, University of California at Berkeley, USA
Osni Marques, LBNL/NERSC, USA

   double precision function zlanhf (character NORM, character TRANSR,
       character UPLO, integer N, complex*16, dimension( 0: * ) A, double
       precision, dimension( 0: * ) WORK)

ZLANHF returns the value of the 1-norm, or the Frobenius norm, or the infinity norm, or the element of largest absolute value of a Hermitian matrix in RFP format. Periodt.

Purpose ✨

ZLANHF returns the value of the one norm, or the Frobenius norm, or the infinity norm, or the element of largest absolute value of a complex Hermitian matrix A in RFP format.

Returns 💅

ZLANHF

             ZLANHF = ( max(abs(A(i,j))), NORM = 'M' or 'm'
                      (
                      ( norm1(A),         NORM = '1', 'O' or 'o'
                      (
                      ( normI(A),         NORM = 'I' or 'i'
                      (
                      ( normF(A),         NORM = 'F', 'f', 'E' or 'e'

where norm1 denotes the one norm of a matrix (maximum column sum), normI denotes the infinity norm of a matrix (maximum row sum) and normF denotes the Frobenius norm of a matrix (square root of sum of squares). Note that max(abs(A(i,j))) is not a matrix norm. iykyk

Parameters 🍓

NORM — NORM is CHARACTER. Specifies the value to be returned in ZLANHF as described above.
TRANSR — TRANSR is CHARACTER. Specifies whether the RFP format of A is normal or conjugate-transposed format.
- = 'N': RFP format is Normal
- = 'C': RFP format is Conjugate-transposed
UPLO — UPLO is CHARACTER. On entry, UPLO specifies whether the RFP matrix A came from an upper or lower triangular matrix as follows:
- UPLO = 'U' or 'u': RFP A came from an upper triangular matrix
- UPLO = 'L' or 'l': RFP A came from a lower triangular matrix
N — N is INTEGER. The order of the matrix A. N >= 0. When N = 0, ZLANHF is set to zero.
A — A is COMPLEX*16 array, dimension ( N*(N+1)/2 );. On entry, the matrix A in RFP Format. RFP Format is described by TRANSR, UPLO and N as follows: If TRANSR='N' then RFP A is (0:N,0:K-1) when N is even; K=N/2. RFP A is (0:N-1,0:K) when N is odd; K=N/2. If TRANSR = 'C' then RFP is the Conjugate-transpose of RFP A as defined when TRANSR = 'N'. The contents of RFP A are defined by UPLO as follows: If UPLO = 'U' the RFP A contains the ( N*(N+1)/2 ) elements of upper packed A either in normal or conjugate-transpose Format. If UPLO = 'L' the RFP A contains the ( N*(N+1) /2 ) elements of lower packed A either in normal or conjugate-transpose Format. The LDA of RFP A is (N+1)/2 when TRANSR = 'C'. When TRANSR is 'N' the LDA is N+1 when N is even and is N when is odd. See the Note below for more details. Unchanged on exit.
WORK — WORK is DOUBLE PRECISION array, dimension (LWORK), where LWORK >= N when NORM = 'I' or '1' or 'O'; otherwise, WORK is not referenced.

Author 🦋

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

Further Details 🔥

First up, Standard Packed Format when N is even. Example where N = 6:

                 AP is Upper             AP is Lower

              00 01 02 03 04 05       00
                 11 12 13 14 15       10 11
                    22 23 24 25       20 21 22
                       33 34 35       30 31 32 33
                          44 45       40 41 42 43 44
                             55       50 51 52 53 54 55

Let TRANSR = 'N'. RFP holds AP as follows: For UPLO = 'U' the upper trapezoid A(0:5,0:2) consists of the last three columns of AP upper. The lower triangle A(4:6,0:2) consists of conjugate-transpose of the first three columns of AP upper. For UPLO = 'L' the lower trapezoid A(1:6,0:2) consists of the first three columns of AP lower. The upper triangle A(0:2,0:2) consists of conjugate-transpose of the last three columns of AP lower. To denote conjugate we place -- above the element. This covers the case N even and TRANSR = 'N'.

                    RFP A                   RFP A

                                           -- -- --
                   03 04 05                33 43 53
                                              -- --
                   13 14 15                00 44 54
                                                 --
                   23 24 25                10 11 55

                   33 34 35                20 21 22
                   --
                   00 44 45                30 31 32
                   -- --
                   01 11 55                40 41 42
                   -- -- --
                   02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- -- --                -- -- -- -- -- --
                03 13 23 33 00 01 02    33 00 10 20 30 40 50
                -- -- -- -- --                -- -- -- -- --
                04 14 24 34 44 11 12    43 44 11 21 31 41 51
                -- -- -- -- -- --                -- -- -- --
                05 15 25 35 45 55 22    53 54 55 22 32 42 52

We next consider Standard Packed Format when N is odd. Example where N = 5:

                AP is Upper                 AP is Lower

              00 01 02 03 04              00
                 11 12 13 14              10 11
                    22 23 24              20 21 22
                       33 34              30 31 32 33
                          44              40 41 42 43 44

For UPLO = 'U' the upper trapezoid A(0:4,0:2) consists of the last three columns of AP upper. The lower triangle A(3:4,0:1) consists of conjugate-transpose of the first two columns of AP upper.

For UPLO = 'L' the lower trapezoid A(0:4,0:2) consists of the first three columns of AP lower. The upper triangle A(0:1,1:2) consists of conjugate-transpose of the last two columns of AP lower.

To denote conjugate we place -- above the element. This covers the case N odd and TRANSR = 'N'.

                    RFP A                   RFP A

                                              -- --
                   02 03 04                00 33 43
                                                 --
                   12 13 14                10 11 44

                   22 23 24                20 21 22
                   --
                   00 33 34                30 31 32
                   -- --
                   01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- --                   -- -- -- -- -- --
                02 12 22 00 01             00 10 20 30 40 50
                -- -- -- --                   -- -- -- -- --
                03 13 23 33 11             33 11 21 31 41 51
                -- -- -- -- --                   -- -- -- --
                04 14 24 34 44             43 44 22 32 42 52

✨ `zlarscl2` ✨

subroutine zlarscl2 (integer M, integer N, double precision, dimension( * ) D,
    complex*16, dimension( ldx, * ) X, integer LDX)

okay so ZLARSCL2 does a reciprocal diagonal scaling on a matrix, bestie 💅

🎀 Purpose 🎀

ZLARSCL2 performs a reciprocal diagonal scaling on a matrix:

  x <-- inv(D) * x

where the DOUBLE PRECISION diagonal matrix D is stored as a vector.

ngl this one's on its way out — eventually to be replaced by BLAS_zge_diag_scale in the new BLAS standard. so like, iconic but retiring 💀

🌸 Parameters 🌸

M — M is INTEGER. The number of rows of D and X. M >= 0.
N — N is INTEGER. The number of columns of X. N >= 0.
D — D is DOUBLE PRECISION array, length M. Diagonal matrix D, stored as a vector of length M.
X — X is COMPLEX*16 array, dimension (LDX,N). On entry, the matrix X to be scaled by D. On exit, the scaled matrix. ✨
LDX — LDX is INTEGER. The leading dimension of the matrix X. LDX >= M.

💜 Author 💜

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🦋 `zlarz` 🦋

subroutine zlarz (character SIDE, integer M, integer N, integer L,
    complex*16, dimension( * ) V, integer INCV, complex*16 TAU, complex*16,
    dimension( ldc, * ) C, integer LDC, complex*16, dimension( * ) WORK)

ZLARZ applies an elementary reflector (as returned by stzrzf) to a general matrix. periodt 💅

🎀 Purpose 🎀

ZLARZ applies a complex elementary reflector H to a complex M-by-N matrix C, from either the left or the right. H is represented in the form

      H = I - tau * v * v**H

where tau is a complex scalar and v is a complex vector.

If tau = 0, then H is taken to be the unit matrix.

To apply H**H (the conjugate transpose of H), supply conjg(tau) instead tau.

H is a product of k elementary reflectors as returned by ZTZRZF.

🌸 Parameters 🌸

SIDE — SIDE is CHARACTER*1
- = 'L': form H * C
- = 'R': form C * H
M — M is INTEGER. The number of rows of the matrix C.
N — N is INTEGER. The number of columns of the matrix C.
L — L is INTEGER. The number of entries of the vector V containing the meaningful part of the Householder vectors. If SIDE = 'L', M >= L >= 0, if SIDE = 'R', N >= L >= 0.
V — V is COMPLEX*16 array, dimension (1+(L-1)*abs(INCV)). The vector v in the representation of H as returned by ZTZRZF. V is not used if TAU = 0.
INCV — INCV is INTEGER. The increment between elements of v. INCV <> 0.
TAU — TAU is COMPLEX*16. The value tau in the representation of H.
C — C is COMPLEX*16 array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by the matrix H * C if SIDE = 'L', or C * H if SIDE = 'R'.
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX*16 array, dimension (N) if SIDE = 'L' or (M) if SIDE = 'R'.

💜 Author 💜

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🌈 Contributors 🌈

A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville, USA

⭐ Further Details ⭐

🫶 `zlarzb` 🫶

subroutine zlarzb (character SIDE, character TRANS, character DIRECT,
    character STOREV, integer M, integer N, integer K, integer L,
    complex*16, dimension( ldv, * ) V, integer LDV, complex*16, dimension(
    ldt, * ) T, integer LDT, complex*16, dimension( ldc, * ) C, integer LDC,
    complex*16, dimension( ldwork, * ) WORK, integer LDWORK)

ZLARZB applies a block reflector or its conjugate-transpose to a general matrix, no cap 🔥

🎀 Purpose 🎀

ZLARZB applies a complex block reflector H or its transpose H**H to a complex distributed M-by-N C from the left or the right.

rn only STOREV = 'R' and DIRECT = 'B' are supported, bestie — the rest are a "not yet" situation 🙈

🌸 Parameters 🌸

SIDE — SIDE is CHARACTER*1
- = 'L': apply H or H**H from the Left
- = 'R': apply H or H**H from the Right
TRANS — TRANS is CHARACTER*1
- = 'N': apply H (No transpose)
- = 'C': apply H**H (Conjugate transpose)
DIRECT — DIRECT is CHARACTER*1. Indicates how H is formed from a product of elementary reflectors
- = 'F': H = H(1) H(2) . . . H(k) (Forward, not supported yet)
- = 'B': H = H(k) . . . H(2) H(1) (Backward)
STOREV — STOREV is CHARACTER*1. Indicates how the vectors which define the elementary reflectors are stored:
- = 'C': Columnwise (not supported yet)
- = 'R': Rowwise
M — M is INTEGER. The number of rows of the matrix C.
N — N is INTEGER. The number of columns of the matrix C.
K — K is INTEGER. The order of the matrix T (= the number of elementary reflectors whose product defines the block reflector).
L — L is INTEGER. The number of columns of the matrix V containing the meaningful part of the Householder reflectors. If SIDE = 'L', M >= L >= 0, if SIDE = 'R', N >= L >= 0.
V — V is COMPLEX*16 array, dimension (LDV,NV). If STOREV = 'C', NV = K; if STOREV = 'R', NV = L.
LDV — LDV is INTEGER. The leading dimension of the array V. If STOREV = 'C', LDV >= L; if STOREV = 'R', LDV >= K.
T — T is COMPLEX*16 array, dimension (LDT,K). The triangular K-by-K matrix T in the representation of the block reflector.
LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= K.
C — C is COMPLEX*16 array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by H*C or H**H*C or C*H or C*H**H. 💅
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX*16 array, dimension (LDWORK,K).
LDWORK — LDWORK is INTEGER. The leading dimension of the array WORK. If SIDE = 'L', LDWORK >= max(1,N); if SIDE = 'R', LDWORK >= max(1,M).

💜 Author 💜

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🌈 Contributors 🌈

A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville, USA

⭐ Further Details ⭐

🧚 `zlarzt` 🧚

subroutine zlarzt (character DIRECT, character STOREV, integer N, integer K,
    complex*16, dimension( ldv, * ) V, integer LDV, complex*16, dimension( * )
    TAU, complex*16, dimension( ldt, * ) T, integer LDT)

ZLARZT forms the triangular factor T of a block reflector H = I - vtvH. it's giving ✨linear algebra✨ 💅

🎀 Purpose 🎀

ZLARZT forms the triangular factor T of a complex block reflector H of order > n, which is defined as a product of k elementary reflectors.

If DIRECT = 'F', H = H(1) H(2) . . . H(k) and T is upper triangular;

If DIRECT = 'B', H = H(k) . . . H(2) H(1) and T is lower triangular.

If STOREV = 'C', the vector which defines the elementary reflector H(i) is stored in the i-th column of the array V, and

   H  =  I - V * T * V**H

If STOREV = 'R', the vector which defines the elementary reflector H(i) is stored in the i-th row of the array V, and

   H  =  I - V**H * T * V

currently, only STOREV = 'R' and DIRECT = 'B' are supported — the rest are on the "not supported yet" list 🙈

🌸 Parameters 🌸

DIRECT — DIRECT is CHARACTER*1. Specifies the order in which the elementary reflectors are multiplied to form the block reflector:
- = 'F': H = H(1) H(2) . . . H(k) (Forward, not supported yet)
- = 'B': H = H(k) . . . H(2) H(1) (Backward)
STOREV — STOREV is CHARACTER*1. Specifies how the vectors which define the elementary reflectors are stored (see also Further Details):
- = 'C': columnwise (not supported yet)
- = 'R': rowwise
N — N is INTEGER. The order of the block reflector H. N >= 0.
K — K is INTEGER. The order of the triangular factor T (= the number of elementary reflectors). K >= 1.
V —
V — COMPLEX*16 array, and its dimension depends on the vibe bestie: (LDV,K) if STOREV = 'C', or (LDV,N) if STOREV = 'R'. This is literally the matrix V. See further details down below 👇
LDV — INTEGER. It's the leading dimension of the array V. If STOREV = 'C' then LDV >= max(1,N); and if STOREV = 'R' then LDV >= K. No cap. ✨
TAU — COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i). Periodt.
T — COMPLEX*16 array, dimension (LDT,K). It's the k by k triangular factor T of the block reflector 🎀. If DIRECT = 'F', then T is upper triangular; if DIRECT = 'B', then T is lower triangular. The rest of the array is literally not used, so don't stress about it 🙈.
LDT — INTEGER. The leading dimension of the array T. LDT >= K. That's it, that's the rule 💅

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Contributors:

A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville, USA

Further Details:

Okay so the shape of the matrix V and the storage of the vectors that define the H(i) is best illustrated by this example with n = 5 and k = 3. The elements equal to 1 are not stored — the corresponding array elements get modified but restored on exit. The rest of the array is not used, bestie, we said it once and we'll say it again 💖

DIRECT = 'F' and STOREV = 'C':         DIRECT = 'F' and STOREV = 'R':

                                             ______V_____
        ( v1 v2 v3 )                        /            \
        ( v1 v2 v3 )                      ( v1 v1 v1 v1 v1 . . . . 1 )
    V = ( v1 v2 v3 )                      ( v2 v2 v2 v2 v2 . . . 1   )
        ( v1 v2 v3 )                      ( v3 v3 v3 v3 v3 . . 1     )
        ( v1 v2 v3 )
           .  .  .
           .  .  .
           1  .  .
              1  .
                 1

DIRECT = 'B' and STOREV = 'C':         DIRECT = 'B' and STOREV = 'R':

                                                       ______V_____
           1                                          /            \
           .  1                           ( 1 . . . . v1 v1 v1 v1 v1 )
           .  .  1                        ( . 1 . . . v2 v2 v2 v2 v2 )
           .  .  .                        ( . . 1 . . v3 v3 v3 v3 v3 )
           .  .  .
        ( v1 v2 v3 )
        ( v1 v2 v3 )
    V = ( v1 v2 v3 )
        ( v1 v2 v3 )
        ( v1 v2 v3 )

subroutine zlascl2

subroutine zlascl2 (integer M, integer N, double precision, dimension( * ) D, complex*16, dimension( ldx, * ) X, integer LDX)

ZLASCL2 performs diagonal scaling on a matrix. It's giving glow-up but for math ✨

Purpose:

ZLASCL2 performs a diagonal scaling on a matrix:
  x <-- D * x
where the DOUBLE PRECISION diagonal matrix D is stored as a vector.

Eventually to be replaced by BLAS_zge_diag_scale in the new BLAS
standard.

Just a heads up bestie: this one is eventually to be replaced by BLAS_zge_diag_scale in the new BLAS standard. So enjoy it while it lasts 💀

Parameters

M — INTEGER. The number of rows of D and X. M >= 0. (so no negative rows, we're not doing that)
N — INTEGER. The number of columns of X. N >= 0.
D — DOUBLE PRECISION array, length M. It's the diagonal matrix D, stored as a vector of length M 🎀
X — COMPLEX*16 array, dimension (LDX,N). On entry, the matrix X to be scaled by D. On exit, the scaled matrix. The transformation arc, iconic 🔥
LDX — INTEGER. The leading dimension of the matrix X. LDX >= M.

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

subroutine zlatrz

subroutine zlatrz (integer M, integer N, integer L, complex*16, dimension( lda, * ) A, integer LDA, complex*16, dimension( * ) TAU, complex*16, dimension( * ) WORK)

ZLATRZ factors an upper trapezoidal matrix by means of unitary transformations. Main character behavior fr fr 👑

Purpose:

ZLATRZ factors the M-by-(M+L) complex upper trapezoidal matrix
[ A1 A2 ] = [ A(1:M,1:M) A(1:M,N-L+1:N) ] as ( R  0 ) * Z by means
of unitary transformations, where  Z is an (M+L)-by-(M+L) unitary
matrix and, R and A1 are M-by-M upper triangular matrices.

Parameters

M — INTEGER. The number of rows of the matrix A. M >= 0.
N — INTEGER. The number of columns of the matrix A. N >= 0.
L — INTEGER. The number of columns of the matrix A containing the meaningful part of the Householder vectors. N-M >= L >= 0. (yes, it really is bounded on both sides, don't test it 🫶)
A — COMPLEX*16 array, dimension (LDA,N). On entry, the leading M-by-N upper trapezoidal part of the array A must contain the matrix to be factorized. On exit, the leading M-by-M upper triangular part of A contains the upper triangular matrix R, and elements N-L+1 to N of the first M rows of A, together with the array TAU, represent the unitary matrix Z as a product of M elementary reflectors. So much lore in one array 😭
LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,M).
TAU — COMPLEX*16 array, dimension (M). The scalar factors of the elementary reflectors 💅
WORK — COMPLEX*16 array, dimension (M).

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Contributors:

A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville, USA

Further Details:

The factorization is obtained by Householder's method (iconic algorithm, we stan). The kth transformation matrix, Z( k ), which is used to introduce zeros into the ( m - k + 1 )th row of A, is given in the form

Z( k ) = ( I     0   ),
         ( 0  T( k ) )

where

T( k ) = I - tau*u( k )*u( k )**H,   u( k ) = (   1    ),
                                                (   0    )
                                                ( z( k ) )

tau is a scalar and z( k ) is an l element vector. tau and z( k ) are chosen to annihilate the elements of the kth row of A2. ✨

The scalar tau is returned in the kth element of TAU and the vector u( k ) in the kth row of A2, such that the elements of z( k ) are in a( k, l + 1 ), ..., a( k, n ). The elements of R are returned in the upper triangular part of A1.

Z is given by

Z =  Z( 1 ) * Z( 2 ) * ... * Z( m ).

subroutine zpbcon

subroutine zpbcon (character UPLO, integer N, integer KD, complex*16, dimension( ldab, * ) AB, integer LDAB, double precision ANORM, double precision RCOND, complex*16, dimension( * ) WORK, double precision, dimension( * ) RWORK, integer INFO)

ZPBCON 💖

Purpose:

ZPBCON estimates the reciprocal of the condition number (in the 1-norm) of a complex Hermitian positive definite band matrix using the Cholesky factorization A = U**H*U or A = L*L**H computed by ZPBTRF.

An estimate is obtained for norm(inv(A)), and the reciprocal of the condition number is computed as

RCOND = 1 / (ANORM * norm(inv(A))).

Parameters

UPLO — CHARACTER*1. = 'U': Upper triangular factor stored in AB; = 'L': Lower triangular factor stored in AB. Pick your fighter 🎀
N — INTEGER. The order of the matrix A. N >= 0.
KD — INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of sub-diagonals if UPLO = 'L'. KD >= 0.
AB — COMPLEX*16 array, dimension (LDAB,N). The triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H of the band matrix A, stored in the first KD+1 rows of the array. The j-th column of U or L is stored in the j-th column of the array AB as follows:
- if UPLO ='U', AB(kd+1+i-j,j) = U(i,j) for max(1,j-kd)<=i<=j;
- if UPLO ='L', AB(1+i-j,j) = L(i,j) for j<=i<=min(n,j+kd).
LDAB — INTEGER. The leading dimension of the array AB. LDAB >= KD+1.
ANORM — DOUBLE PRECISION. The 1-norm (or infinity-norm) of the Hermitian band matrix A.
RCOND — DOUBLE PRECISION. The reciprocal of the condition number of the matrix A, computed as RCOND = 1/(ANORM * AINVNM), where AINVNM is an estimate of the 1-norm of inv(A) computed in this routine.
WORK — COMPLEX*16 array, dimension (2*N).
RWORK — DOUBLE PRECISION array, dimension (N).
INFO — INTEGER. Exit status bestie:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 💀

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

subroutine zpbequ

subroutine zpbequ (character UPLO, integer N, integer KD, complex*16, dimension( ldab, * ) AB, integer LDAB, double precision, dimension( * ) S, double precision SCOND, double precision AMAX, integer INFO)

ZPBEQU 🌸

Purpose:

ZPBEQU computes row and column scalings intended to equilibrate a Hermitian positive definite band matrix A and reduce its condition number (with respect to the two-norm). S contains the scale factors, S(i) = 1/sqrt(A(i,i)), chosen so that the scaled matrix B with elements B(i,j) = S(i)*A(i,j)*S(j) has ones on the diagonal. This choice of S puts the condition number of B within a factor N of the smallest possible condition number over all possible diagonal scalings. It's giving ✨optimization✨

Parameters

UPLO — CHARACTER*1. = 'U': Upper triangular of A is stored; = 'L': Lower triangular of A is stored. Choose wisely 👑
N — INTEGER. The order of the matrix A. N >= 0.
KD — INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
AB —

AB is a COMPLEX*16 array, dimension (LDAB,N) — it's holding the upper or lower triangle of the Hermitian band matrix A, and honestly the whole thing gets tucked into the first KD+1 rows of the array. The j-th column of A lives in the j-th column of the array AB, like this:

if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+kd).

LDAB — it's an INTEGER, bestie, and it's the leading dimension of the array A. The vibe check it has to pass: LDAB >= KD+1. 💅
S — a DOUBLE PRECISION array, dimension (N). If INFO = 0, then S contains the scale factors for A. That's it, that's the whole job. ✨
SCOND — a DOUBLE PRECISION. If INFO = 0, S contains the ratio of the smallest S(i) to the largest S(i). And here's the tea: if SCOND >= 0.1 and AMAX is neither too large nor too small, it is not worth scaling by S. So don't do it. Save yourself. 🙈
AMAX — a DOUBLE PRECISION, the absolute value of the largest matrix element. If AMAX is very close to overflow or very close to underflow, then the matrix should be scaled. It's giving "handle with care". 🔥
INFO — an INTEGER, the receipts:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. Not iconic. 💀
- > 0: if INFO = i, the i-th diagonal element is nonpositive.

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🦋 subroutine zpbrfs 🦋

subroutine zpbrfs (character UPLO, integer N, integer KD, integer NRHS,
    complex*16, dimension( ldab, * ) AB, integer LDAB, complex*16,
    dimension( ldafb, * ) AFB, integer LDAFB, complex*16, dimension( ldb, *
    ) B, integer LDB, complex*16, dimension( ldx, * ) X, integer LDX, double
    precision, dimension( * ) FERR, double precision, dimension( * ) BERR,
    complex*16, dimension( * ) WORK, double precision, dimension( * ) RWORK,
    integer INFO)

ZPBRFS

Purpose:

ZPBRFS improves the computed solution to a system of linear equations when the coefficient matrix is Hermitian positive definite and banded, and it also provides error bounds and backward error estimates for the solution. So it's not just solving — it's solving and telling you how much you should trust it. Main character behaviour, honestly. 💖

Parameters

UPLO — UPLO is CHARACTER*1:
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
KD — KD is INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
NRHS — NRHS is INTEGER. The number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >= 0.
AB — AB is COMPLEX*16 array, dimension (LDAB,N). The upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:

if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+kd).

LDAB — LDAB is INTEGER. The leading dimension of the array AB. LDAB >= KD+1.
AFB — AFB is COMPLEX*16 array, dimension (LDAFB,N). The triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H of the band matrix A as computed by ZPBTRF, in the same storage format as A (see AB). Same layout, different era. ✨
LDAFB — LDAFB is INTEGER. The leading dimension of the array AFB. LDAFB >= KD+1.
B — B is COMPLEX*16 array, dimension (LDB,NRHS). The right hand side matrix B.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
X — X is COMPLEX*16 array, dimension (LDX,NRHS). On entry, the solution matrix X, as computed by ZPBTRS. On exit, the improved solution matrix X. Glow up incoming. 🦋
LDX — LDX is INTEGER. The leading dimension of the array X. LDX >= max(1,N).
FERR — FERR is DOUBLE PRECISION array, dimension (NRHS). The estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error. Slightly dramatic, but honest. 😌
BERR — BERR is DOUBLE PRECISION array, dimension (NRHS). The componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution).
WORK — WORK is COMPLEX*16 array, dimension (2*N)
RWORK — RWORK is DOUBLE PRECISION array, dimension (N)
INFO — INFO is INTEGER:
- = 0: successful exit 🎀
- < 0: if INFO = -i, the i-th argument had an illegal value

Internal Parameters:

ITMAX is the maximum number of steps of iterative refinement. Just so you know the limit, babe. 💅

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌸 subroutine zpbstf 🌸

subroutine zpbstf (character UPLO, integer N, integer KD, complex*16,
    dimension( ldab, * ) AB, integer LDAB, integer INFO)

ZPBSTF

Purpose:

ZPBSTF computes a split Cholesky factorization of a complex Hermitian positive definite band matrix A.

This routine is designed to be used in conjunction with ZHBGST. They're a package deal, fr fr. 🫶

The factorization has the form A = S**H*S where S is a band matrix of the same bandwidth as A and the following structure:

S = ( U    )
    ( M  L )

where U is upper triangular of order m = (n+kd)/2, and L is lower triangular of order n-m.

Parameters

UPLO — UPLO is CHARACTER*1:
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
KD — KD is INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
AB — AB is COMPLEX*16 array, dimension (LDAB,N). On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first kd+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:

if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+kd).

On exit, if INFO = 0, the factor S from the split Cholesky factorization A = S**H*S. See Further Details. 👀

LDAB — LDAB is INTEGER. The leading dimension of the array AB. LDAB >= KD+1.
INFO — INFO is INTEGER:
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, the factorization could not be completed, because the updated element a(i,i) was negative; the matrix A is not positive definite. And that's a whole tragedy, bestie. 😭

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details:

The band storage scheme is illustrated by the following example, when N = 7, KD = 2:

S = ( s11  s12  s13                     )
    (      s22  s23  s24                )
    (           s33  s34                )
    (                s44                )
    (           s53  s54  s55           )
    (                s64  s65  s66      )
    (                     s75  s76  s77 )

If UPLO = 'U', the array AB holds:

on entry:                          on exit:

 *    *   a13  a24  a35  a46  a57   *    *   s13  s24  s53**H s64**H s75**H
 *   a12  a23  a34  a45  a56  a67   *   s12  s23  s34  s54**H s65**H s76**H
a11  a22  a33  a44  a55  a66  a77  s11  s22  s33  s44  s55    s66    s77

If UPLO = 'L', the array AB holds:

on entry:                          on exit:

a11  a22  a33  a44  a55  a66  a77  s11    s22    s33    s44  s55  s66  s77
a21  a32  a43  a54  a65  a76   *   s12**H s23**H s34**H s54  s65  s76   *
a31  a42  a53  a64  a64   *    *   s13**H s24**H s53    s64  s75   *    *

Array elements marked * are not used by the routine; s12**H denotes conjg(s12); the diagonal elements of S are real. So cute, so structured. 🌈

🧚 subroutine zpbtf2 🧚

subroutine zpbtf2 (character UPLO, integer N, integer KD, complex*16,
    dimension( ldab, * ) AB, integer LDAB, integer INFO)

ZPBTF2 computes the Cholesky factorization of a symmetric/Hermitian positive definite band matrix (unblocked algorithm).

Purpose:

ZPBTF2 computes the Cholesky factorization of a complex Hermitian positive definite band matrix A.

The factorization has the form

A = U**H * U ,  if UPLO = 'U', or
A = L  * L**H,  if UPLO = 'L',

where U is an upper triangular matrix, U**H is the conjugate transpose of U, and L is lower triangular.

This is the unblocked version of the algorithm, calling Level 2 BLAS. Lowkey the simpler sibling, but it gets the job done. 💜

Parameters

UPLO — UPLO is CHARACTER*1. Specifies whether the upper or lower triangular part of the Hermitian matrix A is stored:
- = 'U': Upper triangular
- = 'L': Lower triangular
N — N is INTEGER. The order of the matrix A. N >= 0.
KD — KD is INTEGER. The number of super-diagonals of the matrix A if UPLO = 'U', or the number of sub-diagonals if UPLO = 'L'. KD >= 0.
AB —

okay so AB is a COMPLEX*16 array, dimension (LDAB,N). On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows: if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j; if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).

On exit, if INFO = 0, the triangular factor U or L from the Cholesky factorization A = U**H *U or A = L*L**H of the band matrix A, in the same storage format as A.

LDAB — LDAB is INTEGER. The leading dimension of the array AB. LDAB >= KD+1.
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -k, the k-th argument had an illegal value
- > 0: if INFO = k, the leading minor of order k is not positive definite, and the factorization could not be completed.

✨ Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

💅 Further Details

The band storage scheme is illustrated by the following example, when N = 6, KD = 2, and UPLO = 'U':

             On entry:                       On exit:

                 *    *   a13  a24  a35  a46      *    *   u13  u24  u35  u46
                 *   a12  a23  a34  a45  a56      *   u12  u23  u34  u45  u56
                a11  a22  a33  a44  a55  a66     u11  u22  u33  u44  u55  u66

Similarly, if UPLO = 'L' the format of A is as follows:

             On entry:                       On exit:

                a11  a22  a33  a44  a55  a66     l11  l22  l33  l44  l55  l66
                a21  a32  a43  a54  a65   *      l21  l32  l43  l54  l65   *
                a31  a42  a53  a64   *    *      l31  l42  l53  l64   *    *

Array elements marked * are not used by the routine.

🦋 `ZPBTRF` (subroutine)

   subroutine zpbtrf (character UPLO, integer N, integer KD, complex*16,
       dimension( ldab, * ) AB, integer LDAB, integer INFO)

Purpose

ZPBTRF computes the Cholesky factorization of a complex Hermitian positive definite band matrix A.

The factorization has the form A = U**H * U, if UPLO = 'U', or A = L * L**H, if UPLO = 'L', where U is an upper triangular matrix and L is lower triangular.

Parameters

UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER The order of the matrix A. N >= 0.
KD — KD is INTEGER The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
AB — AB is COMPLEX*16 array, dimension (LDAB,N) On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows: if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j; if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).

On exit, if INFO = 0, the triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H of the band matrix A, in the same storage format as A.

LDAB — LDAB is INTEGER The leading dimension of the array AB. LDAB >= KD+1.
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, the leading minor of order i is not positive definite, and the factorization could not be completed.

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

Further Details

The band storage scheme is illustrated by the following example, when N = 6, KD = 2, and UPLO = 'U':

             On entry:                       On exit:

                 *    *   a13  a24  a35  a46      *    *   u13  u24  u35  u46
                 *   a12  a23  a34  a45  a56      *   u12  u23  u34  u45  u56
                a11  a22  a33  a44  a55  a66     u11  u22  u33  u44  u55  u66

Similarly, if UPLO = 'L' the format of A is as follows:

             On entry:                       On exit:

                a11  a22  a33  a44  a55  a66     l11  l22  l33  l44  l55  l66
                a21  a32  a43  a54  a65   *      l21  l32  l43  l54  l65   *
                a31  a42  a53  a64   *    *      l31  l42  l53  l64   *    *

Array elements marked * are not used by the routine.

Contributors

Peter Mayes and Giuseppe Radicati, IBM ECSEC, Rome, March 23, 1989

🦋 `ZPBTRS` (subroutine)

   subroutine zpbtrs (character UPLO, integer N, integer KD, integer NRHS,
       complex*16, dimension( ldab, * ) AB, integer LDAB, complex*16,
       dimension( ldb, * ) B, integer LDB, integer INFO)

Purpose

ZPBTRS solves a system of linear equations A*X = B with a Hermitian positive definite band matrix A using the Cholesky factorization A = U**H *U or A = L*L**H computed by ZPBTRF.

Parameters

UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangular factor stored in AB;
- = 'L': Lower triangular factor stored in AB.
N — N is INTEGER The order of the matrix A. N >= 0.
KD — KD is INTEGER The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
NRHS — NRHS is INTEGER The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
AB — AB is COMPLEX*16 array, dimension (LDAB,N) The triangular factor U or L from the Cholesky factorization A = U**H *U or A = L*L**H of the band matrix A, stored in the first KD+1 rows of the array. The j-th column of U or L is stored in the j-th column of the array AB as follows: if UPLO ='U', AB(kd+1+i-j,j) = U(i,j) for max(1,j-kd)<=i<=j; if UPLO ='L', AB(1+i-j,j) = L(i,j) for j<=i<=min(n,j+kd).
LDAB — LDAB is INTEGER The leading dimension of the array AB. LDAB >= KD+1.
B — B is COMPLEX*16 array, dimension (LDB,NRHS) On entry, the right hand side matrix B. On exit, the solution matrix X.
LDB — LDB is INTEGER The leading dimension of the array B. LDB >= max(1,N).
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🦋 `ZPFTRF` (subroutine)

   subroutine zpftrf (character TRANSR, character UPLO, integer N, complex*16,
       dimension( 0: * ) A, integer INFO)

Purpose

ZPFTRF computes the Cholesky factorization of a complex Hermitian positive definite matrix A.

The factorization has the form A = U**H * U, if UPLO = 'U', or A = L * L**H, if UPLO = 'L', where U is an upper triangular matrix and L is lower triangular.

This is the block version of the algorithm, calling Level 3 BLAS.

Parameters

TRANSR — TRANSR is CHARACTER*1
- = 'N': The Normal TRANSR of RFP A is stored;
- = 'C': The Conjugate-transpose TRANSR of RFP A is stored.
UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of RFP A is stored;
- = 'L': Lower triangle of RFP A is stored.
N — N is INTEGER The order of the matrix A. N >= 0.
A — A is COMPLEX*16 array, dimension ( N*(N+1)/2 ); On entry, the Hermitian matrix A in RFP format. RFP format is described by TRANSR, UPLO, and N as follows: If TRANSR = 'N' then RFP A is (0:N,0:k-1) when N is even; k=N/2. RFP A is (0:N-1,0:k) when N is odd; k=N/2. IF TRANSR = 'C' then RFP is the Conjugate-transpose of RFP A as defined when TRANSR = 'N'. The contents of RFP A are defined by UPLO as follows: If UPLO = 'U' the RFP A contains the nt elements of upper packed A. If UPLO = 'L' the RFP A contains the elements of lower packed A. The LDA of RFP A is (N+1)/2 when TRANSR = 'C'. When TRANSR is 'N' the LDA is N+1 when N is even and N is odd. See the Note below for more details.

On exit, if INFO = 0, the factor U or L from the Cholesky factorization RFP A = U**H*U or RFP A = L*L**H.

INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, the leading minor of order i is not positive definite, and the factorization could not be completed.

Further Notes on RFP Format

We first consider Standard Packed Format when N is even. We give an example where N = 6.

                AP is Upper             AP is Lower

              00 01 02 03 04 05       00
                 11 12 13 14 15       10 11
                    22 23 24 25       20 21 22
                       33 34 35       30 31 32 33
                          44 45       40 41 42 43 44
                             55       50 51 52 53 54 55

                    RFP A                   RFP A

okay so the RFP A for the TRANSR = 'N' case lands like this — those little -- marks are literally floating above the element they belong to, showing you where the conjugate lives:

                                           -- -- --
                   03 04 05                33 43 53
                                              -- --
                   13 14 15                00 44 54
                                                 --
                   23 24 25                10 11 55

                   33 34 35                20 21 22
                   --
                   00 44 45                30 31 32
                   -- --
                   01 11 55                40 41 42
                   -- -- --
                   02 12 22                50 51 52

Now let TRANSR = 'C'. In both UPLO cases, RFP A is just the conjugate-transpose of the RFP A above. So one therefore gets:

                      RFP A                   RFP A

                -- -- -- --                -- -- -- -- -- --
                03 13 23 33 00 01 02    33 00 10 20 30 40 50
                -- -- -- -- --                -- -- -- -- --
                04 14 24 34 44 11 12    43 44 11 21 31 41 51
                -- -- -- -- -- --                -- -- -- --
                05 15 25 35 45 55 22    53 54 55 22 32 42 52

We next consider Standard Packed Format when N is odd — we give an example where N = 5.

                AP is Upper                 AP is Lower

              00 01 02 03 04              00
                 11 12 13 14              10 11
                    22 23 24              20 21 22
                       33 34              30 31 32 33
                          44              40 41 42 43 44

Let TRANSR = 'N'. RFP holds AP as follows:

For UPLO = 'U' the upper trapezoid A(0:4,0:2) consists of the last three columns of AP upper. The lower triangle A(3:4,0:1) consists of conjugate-transpose of the first two columns of AP upper.
For UPLO = 'L' the lower trapezoid A(0:4,0:2) consists of the first three columns of AP lower. The upper triangle A(0:1,1:2) consists of conjugate-transpose of the last two columns of AP lower.

To denote conjugate we place -- above the element. This covers the case N odd and TRANSR = 'N'.

                    RFP A                   RFP A

                                              -- --
                   02 03 04                00 33 43
                                                 --
                   12 13 14                10 11 44

                   22 23 24                20 21 22
                   --
                   00 33 34                30 31 32
                   -- --
                   01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- --                   -- -- -- -- -- --
                02 12 22 00 01             00 10 20 30 40 50
                -- -- -- --                   -- -- -- -- --
                03 13 23 33 11             33 11 21 31 41 51
                -- -- -- -- --                   -- -- -- --
                04 14 24 34 44             43 44 22 32 42 52

Author 💖

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine zpftri (character TRANSR, character UPLO, integer N, complex16, dimension( 0: ) A, integer INFO) 🎀

ZPFTRI ✨

Purpose 🌸

ZPFTRI computes the inverse of a complex Hermitian positive definite matrix A using the Cholesky factorization A = U**H*U or A = L*L**H computed by ZPFTRF.

Parameters 💅

TRANSR — TRANSR is CHARACTER*1
- = 'N': The Normal TRANSR of RFP A is stored;
- = 'C': The Conjugate-transpose TRANSR of RFP A is stored.
UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
A — A is COMPLEX*16 array, dimension ( N*(N+1)/2 ).

On entry, the Hermitian matrix A in RFP format. RFP format is described by TRANSR, UPLO, and N as follows: If TRANSR = 'N' then RFP A is (0:N,0:k-1) when N is even; k=N/2. RFP A is (0:N-1,0:k) when N is odd; k=N/2. IF TRANSR = 'C' then RFP is the Conjugate-transpose of RFP A as defined when TRANSR = 'N'. The contents of RFP A are defined by UPLO as follows: If UPLO = 'U' the RFP A contains the nt elements of upper packed A. If UPLO = 'L' the RFP A contains the elements of lower packed A. The LDA of RFP A is (N+1)/2 when TRANSR = 'C'. When TRANSR is 'N' the LDA is N+1 when N is even and N is odd. See the Note below for more details.

On exit, the Hermitian inverse of the original matrix, in the same storage format.

INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, the (i,i) element of the factor U or L is zero, and the inverse could not be computed.

Author 🦋

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

Further Details 🌈

We first consider Standard Packed Format when N is even. We give an example where N = 6.

    AP is Upper             AP is Lower

  00 01 02 03 04 05       00
     11 12 13 14 15       10 11
        22 23 24 25       20 21 22
           33 34 35       30 31 32 33
              44 45       40 41 42 43 44
                 55       50 51 52 53 54 55

Let TRANSR = 'N'. RFP holds AP as follows:

For UPLO = 'U' the upper trapezoid A(0:5,0:2) consists of the last three columns of AP upper. The lower triangle A(4:6,0:2) consists of conjugate-transpose of the first three columns of AP upper.
For UPLO = 'L' the lower trapezoid A(1:6,0:2) consists of the first three columns of AP lower. The upper triangle A(0:2,0:2) consists of conjugate-transpose of the last three columns of AP lower.

To denote conjugate we place -- above the element. This covers the case N even and TRANSR = 'N'.

                    RFP A                   RFP A

                                           -- -- --
                   03 04 05                33 43 53
                                              -- --
                   13 14 15                00 44 54
                                                 --
                   23 24 25                10 11 55

                   33 34 35                20 21 22
                   --
                   00 44 45                30 31 32
                   -- --
                   01 11 55                40 41 42
                   -- -- --
                   02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- -- --                -- -- -- -- -- --
                03 13 23 33 00 01 02    33 00 10 20 30 40 50
                -- -- -- -- --                -- -- -- -- --
                04 14 24 34 44 11 12    43 44 11 21 31 41 51
                -- -- -- -- -- --                -- -- -- --
                05 15 25 35 45 55 22    53 54 55 22 32 42 52

We next consider Standard Packed Format when N is odd. We give an example where N = 5.

    AP is Upper             AP is Lower

  00 01 02 03 04          00
     11 12 13 14          10 11
        22 23 24          20 21 22
           33 34          30 31 32 33
              44          40 41 42 43 44

Let TRANSR = 'N'. RFP holds AP as follows:

For UPLO = 'U' the upper trapezoid A(0:4,0:2) consists of the last three columns of AP upper. The lower triangle A(3:4,0:1) consists of conjugate-transpose of the first two columns of AP upper.
For UPLO = 'L' the lower trapezoid A(0:4,0:2) consists of the first three columns of AP lower. The upper triangle A(0:1,1:2) consists of conjugate-transpose of the last two columns of AP lower.

To denote conjugate we place -- above the element. This covers the case N odd and TRANSR = 'N'.

                    RFP A                   RFP A

                                              -- --
                   02 03 04                00 33 43
                                                 --
                   12 13 14                10 11 44

                   22 23 24                20 21 22
                   --
                   00 33 34                30 31 32
                   -- --
                   01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- --                   -- -- -- -- -- --
                02 12 22 00 01             00 10 20 30 40 50
                -- -- -- --                   -- -- -- -- --
                03 13 23 33 11             33 11 21 31 41 51
                -- -- -- -- --                   -- -- -- --
                04 14 24 34 44             43 44 22 32 42 52

subroutine zpftrs (character TRANSR, character UPLO, integer N, integer NRHS, complex16, dimension( 0: ) A, complex16, dimension( ldb, ) B, integer LDB, integer INFO) 👑

ZPFTRS ✨

Purpose 💜

ZPFTRS solves a system of linear equations A*X = B with a Hermitian positive definite matrix A using the Cholesky factorization A = U**H*U or A = L*L**H computed by ZPFTRF.

Parameters 🍓

TRANSR — TRANSR is CHARACTER*1
- = 'N': The Normal TRANSR of RFP A is stored;
- = 'C': The Conjugate-transpose TRANSR of RFP A is stored.
UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of RFP A is stored;
- = 'L': Lower triangle of RFP A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
NRHS — NRHS is INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
A — A is COMPLEX*16 array, dimension ( N*(N+1)/2 ). The triangular factor U or L from the Cholesky factorization of RFP A = U**H*U or RFP A = L*L**H, as computed by ZPFTRF. See note below for more details about RFP A.
B — B is COMPLEX*16 array, dimension (LDB,NRHS). On entry, the right hand side matrix B. On exit, the solution matrix X.
LDB
LDB is INTEGER — bestie, this is the leading dimension of the array B. It's gotta be LDB >= max(1,N). No cap. 💅

INFO

INFO is INTEGER
- = 0: successful exit, slay! ✨
- < 0: if INFO = -i, the i-th argument had an illegal value. So like, if you passed something sus, it'll tell you which one. 😭

✨ Author ✨

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

These iconic institutions and NAG Ltd. wrote this. Respect. 👑

Further Details:

Okay so first, let's talk Standard Packed Format when N is even. We give an example where N = 6.

    AP is Upper             AP is Lower

  00 01 02 03 04 05       00
     11 12 13 14 15       10 11
        22 23 24 25       20 21 22
           33 34 35       30 31 32 33
              44 45       40 41 42 43 44
                 55       50 51 52 53 54 55

Let TRANSR = 'N'. RFP holds AP as follows:

For UPLO = 'U' the upper trapezoid A(0:5,0:2) consists of the last three columns of AP upper. The lower triangle A(4:6,0:2) consists of conjugate-transpose of the first three columns of AP upper.
For UPLO = 'L' the lower trapezoid A(1:6,0:2) consists of the first three columns of AP lower. The upper triangle A(0:2,0:2) consists of conjugate-transpose of the last three columns of AP lower.

To denote conjugate we place -- above the element. This covers the case N even and TRANSR = 'N'.

        RFP A                   RFP A

                               -- -- --
       03 04 05                33 43 53
                                  -- --
       13 14 15                00 44 54
                                     --
       23 24 25                10 11 55

       33 34 35                20 21 22
       --
       00 44 45                30 31 32
       -- --
       01 11 55                40 41 42
       -- -- --
       02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

          RFP A                   RFP A

    -- -- -- --                -- -- -- -- -- --
    03 13 23 33 00 01 02    33 00 10 20 30 40 50
    -- -- -- -- --                -- -- -- -- --
    04 14 24 34 44 11 12    43 44 11 21 31 41 51
    -- -- -- -- -- --                -- -- -- --
    05 15 25 35 45 55 22    53 54 55 22 32 42 52

We next consider Standard Packed Format when N is odd. We give an example where N = 5.

    AP is Upper                 AP is Lower

  00 01 02 03 04              00
     11 12 13 14              10 11
        22 23 24              20 21 22
           33 34              30 31 32 33
              44              40 41 42 43 44

Let TRANSR = 'N'. RFP holds AP as follows:

For UPLO = 'U' the upper trapezoid A(0:4,0:2) consists of the last three columns of AP upper. The lower triangle A(3:4,0:1) consists of conjugate-transpose of the first two columns of AP upper.
For UPLO = 'L' the lower trapezoid A(0:4,0:2) consists of the first three columns of AP lower. The upper triangle A(0:1,1:2) consists of conjugate-transpose of the last two columns of AP lower.

To denote conjugate we place -- above the element. This covers the case N odd and TRANSR = 'N'.

        RFP A                   RFP A

                                  -- --
       02 03 04                00 33 43
                                     --
       12 13 14                10 11 44

       22 23 24                20 21 22
       --
       00 33 34                30 31 32
       -- --
       01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

          RFP A                   RFP A

    -- -- --                   -- -- -- -- -- --
    02 12 22 00 01             00 10 20 30 40 50
    -- -- -- --                   -- -- -- -- --
    03 13 23 33 11             33 11 21 31 41 51
    -- -- -- -- --                   -- -- -- --
    04 14 24 34 44             43 44 22 32 42 52

subroutine zppcon (character UPLO, integer N, complex*16, dimension( * ) AP,
    double precision ANORM, double precision RCOND, complex*16, dimension( *
    ) WORK, double precision, dimension( * ) RWORK, integer INFO)

ZPPCON 💖

Purpose

ZPPCON estimates the reciprocal of the condition number (in the 1-norm) of a complex Hermitian positive definite packed matrix using the Cholesky factorization A = U**H*U or A = L*L**H computed by ZPPTRF.

An estimate is obtained for norm(inv(A)), and the reciprocal of the condition number is computed as RCOND = 1 / (ANORM * norm(inv(A))).

Parameters

UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N is INTEGER The order of the matrix A. N >= 0.
AP is COMPLEX*16 array, dimension (N*(N+1)/2) The triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H, packed columnwise in a linear array. The j-th column of U or L is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = U(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = L(i,j) for j<=i<=n.
ANORM is DOUBLE PRECISION The 1-norm (or infinity-norm) of the Hermitian matrix A.
RCOND is DOUBLE PRECISION The reciprocal of the condition number of the matrix A, computed as RCOND = 1/(ANORM * AINVNM), where AINVNM is an estimate of the 1-norm of inv(A) computed in this routine.
WORK is COMPLEX*16 array, dimension (2*N)
RWORK is DOUBLE PRECISION array, dimension (N)
INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine zppequ (character UPLO, integer N, complex*16, dimension( * ) AP,
    double precision, dimension( * ) S, double precision SCOND, double
    precision AMAX, integer INFO)

ZPPEQU ✨

Purpose

ZPPEQU computes row and column scalings intended to equilibrate a Hermitian positive definite matrix A in packed storage and reduce its condition number (with respect to the two-norm). S contains the scale factors, S(i)=1/sqrt(A(i,i)), chosen so that the scaled matrix B with elements B(i,j)=S(i)*A(i,j)*S(j) has ones on the diagonal. This choice of S puts the condition number of B within a factor N of the smallest possible condition number over all possible diagonal scalings.

Parameters

UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N is INTEGER The order of the matrix A. N >= 0.
AP is COMPLEX*16 array, dimension (N*(N+1)/2) The upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.
S is DOUBLE PRECISION array, dimension (N) If INFO = 0, S contains the scale factors for A.
SCOND is DOUBLE PRECISION If INFO = 0, S contains the ratio of the smallest S(i) to the largest S(i). If SCOND >= 0.1 and AMAX is neither too large nor too small, it is not worth scaling by S.
AMAX is DOUBLE PRECISION Absolute value of largest matrix element. If AMAX is very close to overflow or very close to underflow, the matrix should be scaled.
INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, the i-th diagonal element is nonpositive.

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine zpprfs (character UPLO, integer N, integer NRHS, complex*16,
    dimension( * ) AP, complex*16, dimension( * ) AFP, complex*16,
    dimension( ldb, * ) B, integer LDB, complex*16, dimension( ldx, * ) X,
    integer LDX, double precision, dimension( * ) FERR, double precision,
    dimension( * ) BERR, complex*16, dimension( * ) WORK, double precision,
    dimension( * ) RWORK, integer INFO)

ZPPRFS 🦋

Purpose

ZPPRFS improves the computed solution to a system of linear equations when the coefficient matrix is Hermitian positive definite and packed, and provides error bounds and backward error estimates for the solution.

Parameters

UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N is INTEGER The order of the matrix A. N >= 0.
NRHS is INTEGER The number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >= 0.
AP is COMPLEX*16 array, dimension (N*(N+1)/2) The upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.
AFP
AFP — COMPLEX*16 array, dimension (N*(N+1)/2). It's the triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H, exactly like DPPTRF/ZPPTRF hands it to you — packed columnwise in a linear array, same format as A (peep the AP deets below bestie 💖).
B — COMPLEX*16 array, dimension (LDB,NRHS). The right hand side matrix B. the vibes we're solving for ✨
LDB — INTEGER. The leading dimension of the array B. Constraint check: LDB >= max(1,N). no skipping this one, she will notice 👀
X — COMPLEX*16 array, dimension (LDX,NRHS). On entry, the solution matrix X, as computed by ZPPTRS. On exit, the improved solution matrix X. glow up era 💅
LDX — INTEGER. The leading dimension of the array X. Constraint check: LDX >= max(1,N).
FERR — DOUBLE PRECISION array, dimension (NRHS). The estimated forward error bound for each solution vector X(j) (that's the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), then FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for RCOND, and it's almost always a slight overestimate of the true error. she's giving "safety margin" energy fr fr 🫶
BERR — DOUBLE PRECISION array, dimension (NRHS). The componentwise relative backward error of each solution vector X(j). That means: the smallest relative change in any element of A or B that makes X(j) an exact solution. tiny number = slay, big number = uh oh 😭
WORK — COMPLEX*16 array, dimension (2*N). scratch space, don't look at her she's working 💜
RWORK — DOUBLE PRECISION array, dimension (N). more scratch space, real-valued this time 🌸
INFO — INTEGER. The status report bestie:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. you passed something cursed, go fix it 💀

🧠 Internal Parameters:

ITMAX is the maximum number of steps of iterative refinement. she'll loop, but only so many times — periodt ✋

👑 Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

the legends themselves, we stan 🫶

⭐ subroutine zpptrf (character UPLO, integer N, complex16, dimension( ) AP, integer INFO)

subroutine zpptrf (character UPLO, integer N, complex*16, dimension( * ) AP, integer INFO)

ZPPTRF

🎯 Purpose:

ZPPTRF computes the Cholesky factorization of a complex Hermitian positive definite matrix A stored in packed format. packed storage girlies rise up 💖

The factorization has the form

A = U**H * U,  if UPLO = 'U', or
A = L  * L**H,  if UPLO = 'L',

where U is an upper triangular matrix and L is lower triangular.

🎀 Parameters

UPLO — CHARACTER*1:
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — INTEGER. The order of the matrix A. N >= 0.
AP — COMPLEX*16 array, dimension (N*(N+1)/2). On entry, the upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.

See below for further details. seriously, the Further Details section eats, don't scroll past it 🦋

On exit, if INFO = 0, the triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H, in the same storage format as A.

INFO — INTEGER:
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value 💀
- > 0: if INFO = i, the leading minor of order i is not positive definite, and the factorization could not be completed. the matrix said no and she meant it 😭

👑 Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🔍 Further Details:

The packed storage scheme is illustrated by the following example when N = 4, UPLO = 'U':

Two-dimensional storage of the Hermitian matrix A:

   a11 a12 a13 a14
       a22 a23 a24
           a33 a34     (aij = conjg(aji))
               a44

Packed storage of the upper triangle of A:

AP = [ a11, a12, a22, a13, a23, a33, a14, a24, a34, a44 ]

see how she folded the whole triangle into one lil line?? iconic. no cap. 👑

⭐ subroutine zpptri (character UPLO, integer N, complex16, dimension( ) AP, integer INFO)

subroutine zpptri (character UPLO, integer N, complex*16, dimension( * ) AP, integer INFO)

ZPPTRI

🎯 Purpose:

ZPPTRI computes the inverse of a complex Hermitian positive definite matrix A using the Cholesky factorization A = U**H*U or A = L*L**H computed by ZPPTRF. she takes the factorization you already did and flips the whole thing 💅

🎀 Parameters

UPLO — CHARACTER*1:
- = 'U': Upper triangular factor is stored in AP;
- = 'L': Lower triangular factor is stored in AP.
N — INTEGER. The order of the matrix A. N >= 0.
AP — COMPLEX*16 array, dimension (N*(N+1)/2). On entry, the triangular factor U or L from the Cholesky factorization A = U**H*U or A = L*L**H, packed columnwise as a linear array. The j-th column of U or L is stored in the array AP as follows:

if UPLO = 'U', AP(i + (j-1)*j/2) = U(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = L(i,j) for j<=i<=n.

On exit, the upper or lower triangle of the (Hermitian) inverse of A, overwriting the input factor U or L. yeah she's not keeping your old factor, that's gone bestie 🙈

INFO — INTEGER:
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value 💀
- > 0: if INFO = i, the (i,i) element of the factor U or L is zero, and the inverse could not be computed. division by zero behavior, absolutely not, we don't do that here 😭

👑 Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

⭐ subroutine zpptrs (character UPLO, integer N, integer NRHS, complex16, dimension( ) AP, complex16, dimension( ldb, ) B, integer LDB, integer INFO)

subroutine zpptrs (character UPLO, integer N, integer NRHS, complex*16, dimension( * ) AP, complex*16, dimension( ldb, * ) B, integer LDB, integer INFO)

ZPPTRS

🎯 Purpose:

ZPPTRS solves a system of linear equations A*X = B with a Hermitian positive definite matrix A in packed storage, using the Cholesky factorization A = U**H * U or A = L * L**H computed by ZPPTRF. the payoff!! you factored, now you solve. main character arc complete 🌈

🎀 Parameters

UPLO — CHARACTER*1:
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — INTEGER. The order of the matrix A. N >= 0.
NRHS — INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0. more columns = more problems solved at once, we love efficiency ✨
AP — COMPLEX*16 array, dimension (N*(N+1)/2). The triangular factor U or L from the Cholesky factorization A = U**H * U or A = L * L**H, packed columnwise in a linear array. The j-th column of U or L is stored in the array AP as follows:

if UPLO = 'U', AP(i + (j-1)*j/2) = U(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = L(i,j) for j<=i<=n.

B — COMPLEX*16 array, dimension (LDB,NRHS). On entry, the right hand side matrix B. On exit, the solution matrix X. she gets replaced in place, glow up style 💖
LDB — INTEGER. The leading dimension of the array B. Constraint check: LDB >= max(1,N).
INFO — INTEGER:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 💀

👑 Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

⭐ subroutine zpstf2 (character UPLO, integer N, complex16, dimension( lda, ) A, integer LDA, integer, dimension( n ) PIV, integer RANK, double precision TOL, double precision, dimension( 2*n ) WORK, integer INFO)

subroutine zpstf2 (character UPLO, integer N, complex*16, dimension( lda, * ) A, integer LDA, integer, dimension( n ) PIV, integer RANK, double precision TOL, double precision, dimension( 2*n ) WORK, integer INFO)

ZPSTF2 computes the Cholesky factorization with complete pivoting of a complex Hermitian positive semidefinite matrix. pivoting?? semidefinite?? ok she's the advanced version, she's got range 💅

🎯 Purpose:

ZPSTF2 computes the Cholesky factorization with complete pivoting of a complex Hermitian positive semidefinite matrix A.

The factorization has the form

P**T * A * P = U**H * U ,  if UPLO = 'U',
P**T * A * P = L  * L**H,  if UPLO = 'L',

where U is an upper triangular matrix and L is lower triangular, and P is stored as vector PIV.

This algorithm does not attempt to check that A is positive semidefinite. she trusts you, which is honestly a little scary — that's on you, not her 😭 This version of the algorithm calls level 2 BLAS. iykyk 🦋

🎀 Parameters

UPLO — CHARACTER*1. Specifies whether the upper or lower triangular part of the symmetric matrix A is stored.
- = 'U': Upper triangular
- = 'L': Lower triangular
N — INTEGER. The order of the matrix A. N >= 0.
A — COMPLEX*16 array, dimension (LDA,N). On entry, the symmetric matrix A. If UPLO = 'U', the leading n by n upper triangular part of A contains the upper triangular part of the matrix A, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading n by n lower triangular part of A contains the lower triangular part of the matrix A, and the strictly upper triangular part of A is not referenced. whatever's on the other side of that diagonal? she literally cannot see it. it does not exist to her. 🙈

On exit, if INFO = 0, the factor U or L from the Cholesky factorization as above.

PIV — INTEGER array, dimension (N). PIV is such that the nonzero entries are P( PIV(K), K ) = 1.
RANK — INTEGER. The rank of A given by the number of steps the algorithm completed. how far she got before she was done, essentially ✨
TOL — DOUBLE PRECISION. User defined tolerance. If TOL < 0, then N*U*MAX( A( K,K ) ) will be used. The algorithm terminates at the (K-1)st step if the pivot <= TOL. you set the bar, she respects the bar 🫶
LDA — INTEGER. The leading dimension of the array A. Constraint check: LDA >= max(1,N).
WORK — DOUBLE PRECISION array, dimension (2*N). Work space. scratch pad, mind ya business 💜
INFO — okay so this one's description is literally mid-sentence in this part of the page, hold that thought bestie, we're picking it right back up 😭
INFO is INTEGER
- < 0: if INFO = -K, the K-th argument had an illegal value,
- = 0: algorithm completed successfully, and
- > 0: the matrix A is either rank deficient with computed rank as returned in RANK, or is not positive semidefinite. See Section 7 of LAPACK Working Note #161 for further information.

no cap, that > 0 case is the one that gets everybody. if INFO comes back positive, A is either rank deficient (and RANK is telling you the rank she actually got to) or it's just not positive semidefinite. either way, go read Section 7 of LAPACK Working Note #161, it's giving required reading 💀

Author 🌸

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine `zpstrf` 💖

   subroutine zpstrf (character UPLO, integer N, complex*16, dimension( lda, *
       ) A, integer LDA, integer, dimension( n ) PIV, integer RANK, double
       precision TOL, double precision, dimension( 2*n ) WORK, integer INFO)

ZPSTRF computes the Cholesky factorization with complete pivoting of a complex Hermitian positive semidefinite matrix.

Purpose ✨

ZPSTRF computes the Cholesky factorization with complete pivoting of a complex Hermitian positive semidefinite matrix A.

bestie, the factorization has the form

   P**T * A * P = U**H * U ,  if UPLO = 'U',
   P**T * A * P = L  * L**H,  if UPLO = 'L',

where U is an upper triangular matrix and L is lower triangular, and P is stored as vector PIV. the way that P just lives inside PIV as a whole vector… iconic behavior honestly 🫶

⚠️ real talk: this algorithm does not attempt to check that A is positive semidefinite. it will not vibe check your matrix for you. you said it was PSD, she believed you, and that's on both of you.

also, heads up: this version of the algorithm calls level 3 BLAS. so she's the blocked, fast, main-character version. 💅

Parameters 🎀

UPLO — CHARACTER*1. Specifies whether the upper or lower triangular part of the symmetric matrix A is stored.
- = 'U': Upper triangular
- = 'L': Lower triangular
N — INTEGER. The order of the matrix A. N >= 0.
A — COMPLEX*16 array, dimension (LDA,N). On entry, the symmetric matrix A. If UPLO = 'U', the leading n by n upper triangular part of A contains the upper triangular part of the matrix A, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading n by n lower triangular part of A contains the lower triangular part of the matrix A, and the strictly upper triangular part of A is not referenced.
- On exit, if INFO = 0, the factor U or L from the Cholesky factorization as above. she ate and left no crumbs, and also left you a factor ✨
LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,N).
PIV — INTEGER array, dimension (N). PIV is such that the nonzero entries are P( PIV(K), K ) = 1.
RANK — INTEGER. The rank of A given by the number of steps the algorithm completed.
TOL — DOUBLE PRECISION. User defined tolerance. If TOL < 0, then N*U*MAX( A(K,K) ) will be used. The algorithm terminates at the (K-1)st step if the pivot <= TOL.
WORK — DOUBLE PRECISION array, dimension (2*N). Work space. yes bestie she needs her little scratch pad, everyone does
INFO — INTEGER.
- < 0: If INFO = -K, the K-th argument had an illegal value,
- = 0: algorithm completed successfully, and
- > 0: the matrix A is either rank deficient with computed rank as returned in RANK, or is not positive semidefinite. See Section 7 of LAPACK Working Note #161 for further information.

Author 💜

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine `zspcon` 🦋

   subroutine zspcon (character UPLO, integer N, complex*16, dimension( * ) AP,
       integer, dimension( * ) IPIV, double precision ANORM, double precision
       RCOND, complex*16, dimension( * ) WORK, integer INFO)

ZSPCON

Purpose 🌈

ZSPCON estimates the reciprocal of the condition number (in the 1-norm) of a complex symmetric packed matrix A using the factorization A = U*D*U**T or A = L*D*L**T computed by ZSPTRF.

An estimate is obtained for norm(inv(A)), and the reciprocal of the condition number is computed as RCOND = 1 / (ANORM * norm(inv(A))).

so basically: how sketchy is your matrix, on a scale of "totally fine" to "girl, do not trust that answer". that's the whole vibe. 🔥

Parameters ⭐

UPLO — CHARACTER*1. Specifies whether the details of the factorization are stored as an upper or lower triangular matrix.
- = 'U': Upper triangular, form is A = U*D*U**T;
- = 'L': Lower triangular, form is A = L*D*L**T.
N — INTEGER. The order of the matrix A. N >= 0.
AP — COMPLEX*16 array, dimension (N*(N+1)/2). The block diagonal matrix D and the multipliers used to obtain the factor U or L as computed by ZSPTRF, stored as a packed triangular matrix.
IPIV — INTEGER array, dimension (N). Details of the interchanges and the block structure of D as determined by ZSPTRF.
ANORM — DOUBLE PRECISION. The 1-norm of the original matrix A.
RCOND — DOUBLE PRECISION. The reciprocal of the condition number of the matrix A, computed as RCOND = 1/(ANORM * AINVNM), where AINVNM is an estimate of the 1-norm of inv(A) computed in this routine.
WORK — COMPLEX*16 array, dimension (2*N)
INFO — INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

Author 🌸

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine `zsprfs` 🧚

   subroutine zsprfs (character UPLO, integer N, integer NRHS, complex*16,
       dimension( * ) AP, complex*16, dimension( * ) AFP, integer, dimension( *
       ) IPIV, complex*16, dimension( ldb, * ) B, integer LDB, complex*16,
       dimension( ldx, * ) X, integer LDX, double precision, dimension( * )
       FERR, double precision, dimension( * ) BERR, complex*16, dimension( * )
       WORK, double precision, dimension( * ) RWORK, integer INFO)

ZSPRFS

Purpose 💫

ZSPRFS improves the computed solution to a system of linear equations when the coefficient matrix is symmetric indefinite and packed, and provides error bounds and backward error estimates for the solution.

she's the glow-up routine. you hand her a mid answer, she hands it back better and also tells you exactly how much you should trust it. that's growth. that's healing. 🫶

Parameters 💖

UPLO — CHARACTER*1.
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — INTEGER. The order of the matrix A. N >= 0.
NRHS — INTEGER. The number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >= 0.
AP — COMPLEX*16 array, dimension (N*(N+1)/2). The upper or lower triangle of the symmetric matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.
AFP — COMPLEX*16 array, dimension (N*(N+1)/2). The factored form of the matrix A. AFP contains the block diagonal matrix D and the multipliers used to obtain the factor U or L from the factorization A = U*D*U**T or A = L*D*L**T as computed by ZSPTRF, stored as a packed triangular matrix.
IPIV — INTEGER array, dimension (N). Details of the interchanges and the block structure of D as determined by ZSPTRF.
B — COMPLEX*16 array, dimension (LDB,NRHS). The right hand side matrix B.
LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,N).
X — COMPLEX*16 array, dimension (LDX,NRHS). On entry, the solution matrix X, as computed by ZSPTRS. On exit, the improved solution matrix X. glow-up complete, bestie ✨
LDX — INTEGER. The leading dimension of the array X. LDX >= max(1,N).
FERR — DOUBLE PRECISION array, dimension (NRHS). The estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error.
BERR — DOUBLE PRECISION array, dimension (NRHS). The componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution).
WORK — COMPLEX*16 array, dimension (2*N)
RWORK — DOUBLE PRECISION array, dimension (N)
INFO — INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

Internal Parameters 🌟

ITMAX is the maximum number of steps of iterative refinement.

Author 🎀

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine `zsptrf` 👑

   subroutine zsptrf (character UPLO, integer N, complex*16, dimension( * ) AP,
       integer, dimension( * ) IPIV, integer INFO)

ZSPTRF

Purpose 🔥

ZSPTRF computes the factorization of a complex symmetric matrix A stored in packed format using the Bunch-Kaufman diagonal pivoting method:

   A = U*D*U**T  or  A = L*D*L**T

where U (or L) is a product of permutation and unit upper (lower) triangular matrices, and D is symmetric and block diagonal with 1-by-1 and 2-by-2 diagonal blocks.

Bunch-Kaufman said "I'll pivot diagonally, and you will DEAL" and honestly? she was right. 1-by-1 and 2-by-2 blocks only, no notes. 💅

Parameters 🌈

UPLO — CHARACTER*1.
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N
N — is INTEGER, bestie. It's the order of the matrix A. And N >= 0, always. 👑
AP — is a COMPLEX*16 array, dimension (N*(N+1)/2). Okay so on entry it's the upper or lower triangle of the symmetric matrix A, packed columnwise into one linear array — no cap, it's just vibes in a straight line. The j-th column of A lives in AP like this:

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.

On exit tho? It's the block diagonal matrix D plus the multipliers used to get the factor U or L, stored as a packed triangular matrix and just straight-up overwriting A (more on that below, iykyk).

IPIV — is an INTEGER array, dimension (N). It holds the details of the interchanges and the block structure of D. So like:
- If IPIV(k) > 0, then rows and columns k and IPIV(k) were interchanged and D(k,k) is a 1-by-1 diagonal block. Simple. 💅
- If UPLO = 'U' and IPIV(k) = IPIV(k-1) < 0, then rows and columns k-1 and -IPIV(k) were interchanged and D(k-1:k,k-1:k) is a 2-by-2 diagonal block.
- If UPLO = 'L' and IPIV(k) = IPIV(k+1) < 0, then rows and columns k+1 and -IPIV(k) were interchanged and D(k:k+1,k:k+1) is a 2-by-2 diagonal block.
INFO — is INTEGER, the little status report at the end, and it goes:
- = 0: successful exit. slay. ✨
- < 0: if INFO = -i, the i-th argument had an illegal value. 🚩
- > 0: if INFO = i, D(i,i) is exactly zero. The factorization has been completed, but the block diagonal matrix D is exactly singular, and division by zero will occur if it is used to solve a system of equations. So like… be careful, bestie, that's a yikes. 💀

Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details 🔍

5-96 - Based on modifications by J. Lewis, Boeing Computer Services Company

If UPLO = 'U', then A = U*D*U**T, where

   U = P(n)*U(n)* ... *P(k)U(k)* ...,

i.e., U is a product of terms P(k)*U(k), where k decreases from n to 1 in steps of 1 or 2, and D is a block diagonal matrix with 1-by-1 and 2-by-2 diagonal blocks D(k). P(k) is a permutation matrix as defined by IPIV(k), and U(k) is a unit upper triangular matrix, such that if the diagonal block D(k) is of order s (s = 1 or 2), then

           (   I    v    0   )   k-s
    U(k) =  (   0    I    0   )   s
           (   0    0    I   )   n-k
              k-s   s   n-k

If UPLO = 'L', then A = L*D*L**T, where

   L = P(1)*L(1)* ... *P(k)*L(k)* ...,

i.e., L is a product of terms P(k)*L(k), where k increases from 1 to n in steps of 1 or 2, and D is a block diagonal matrix with 1-by-1 and 2-by-2 diagonal blocks D(k). P(k) is a permutation matrix as defined by IPIV(k), and L(k) is a unit lower triangular matrix, such that if the diagonal block D(k) is of order s (s = 1 or 2), then

           (   I    0     0   )  k-1
    L(k) =  (   0    I     0   )  s
           (   0    v     I   )  n-k-s+1
              k-1   s  n-k-s+1

🦋 `zsptri`

subroutine zsptri (character UPLO, integer N, complex*16, dimension( * ) AP,
    integer, dimension( * ) IPIV, complex*16, dimension( * ) WORK, integer
    INFO)

Purpose 💖

ZSPTRI computes the inverse of a complex symmetric indefinite matrix A in packed storage, using the factorization A = U*D*U**T or A = L*D*L**T computed by ZSPTRF. Like, it takes the factorization you already did and hands you the inverse. iconic behavior, fr fr.

Parameters 🎀

UPLO — is CHARACTER*1. It specifies whether the details of the factorization are stored as an upper or lower triangular matrix.
- = 'U': Upper triangular, form is A = U*D*U**T;
- = 'L': Lower triangular, form is A = L*D*L**T.
N — is INTEGER. The order of the matrix A. N >= 0.
AP — is COMPLEX*16 array, dimension (N*(N+1)/2). On entry, the block diagonal matrix D and the multipliers used to obtain the factor U or L as computed by ZSPTRF, stored as a packed triangular matrix.

On exit, if INFO = 0, the (symmetric) inverse of the original matrix, stored as a packed triangular matrix. The j-th column of inv(A) is stored in the array AP as follows:

if UPLO = 'U', AP(i + (j-1)*j/2) = inv(A)(i,j) for 1<=i<=j;
if UPLO = 'L',
   AP(i + (j-1)*(2n-j)/2) = inv(A)(i,j) for j<=i<=n.

IPIV — is INTEGER array, dimension (N). Details of the interchanges and the block structure of D as determined by ZSPTRF.
WORK — is COMPLEX*16 array, dimension (N).
INFO — is INTEGER, and it's giving status report:
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, D(i,i) = 0; the matrix is singular and its inverse could not be computed. 💀 no inverse for you, bestie.

Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌸 `zsptrs`

subroutine zsptrs (character UPLO, integer N, integer NRHS, complex*16,
    dimension( * ) AP, integer, dimension( * ) IPIV, complex*16, dimension(
    ldb, * ) B, integer LDB, integer INFO)

Purpose 💫

ZSPTRS solves a system of linear equations A*X = B with a complex symmetric matrix A stored in packed format, using the factorization A = U*D*U**T or A = L*D*L**T computed by ZSPTRF. You did the hard part already, now it just solves it. we love a follow-through. 🫶

Parameters 🌈

UPLO — is CHARACTER*1. Specifies whether the details of the factorization are stored as an upper or lower triangular matrix.
- = 'U': Upper triangular, form is A = U*D*U**T;
- = 'L': Lower triangular, form is A = L*D*L**T.
N — is INTEGER. The order of the matrix A. N >= 0.
NRHS — is INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
AP — is COMPLEX*16 array, dimension (N*(N+1)/2). The block diagonal matrix D and the multipliers used to obtain the factor U or L as computed by ZSPTRF, stored as a packed triangular matrix.
IPIV — is INTEGER array, dimension (N). Details of the interchanges and the block structure of D as determined by ZSPTRF.
B — is COMPLEX*16 array, dimension (LDB,NRHS). On entry, the right hand side matrix B. On exit, the solution matrix X. ✨ the glow-up.
LDB — is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
INFO — is INTEGER, keeping you informed:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value

Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🧚 `zstedc`

subroutine zstedc (character COMPZ, integer N, double precision, dimension(
    * ) D, double precision, dimension( * ) E, complex*16, dimension( ldz, *
    ) Z, integer LDZ, complex*16, dimension( * ) WORK, integer LWORK, double
    precision, dimension( * ) RWORK, integer LRWORK, integer, dimension( * )
    IWORK, integer LIWORK, integer INFO)

Purpose 🔥

ZSTEDC computes all eigenvalues and, optionally, eigenvectors of a symmetric tridiagonal matrix using the divide and conquer method. The eigenvectors of a full or band complex Hermitian matrix can also be found if ZHETRD or ZHPTRD or ZHBTRD has been used to reduce this matrix to tridiagonal form. yes bestie, all of them, go off. 💅

This code makes very mild assumptions about floating point arithmetic. It will work on machines with a guard digit in add/subtract, or on those binary machines without guard digits which subtract like the Cray X-MP, Cray Y-MP, Cray C-90, or Cray-2. It could conceivably fail on hexadecimal or decimal machines without guard digits, but we know of none. See DLAED3 for details.

ngl that's a very specific list of Crays and I'm obsessed with the confidence. 😭

Parameters 💜

COMPZ — is CHARACTER*1, and it picks your adventure:
- = 'N': Compute eigenvalues only.
- = 'I': Compute eigenvectors of tridiagonal matrix also.
- = 'V': Compute eigenvectors of original Hermitian matrix also. On entry, Z contains the unitary matrix used to reduce the original matrix to tridiagonal form.
N — is INTEGER. The dimension of the symmetric tridiagonal matrix. N >= 0.
D — is DOUBLE PRECISION array, dimension (N). On entry, the diagonal elements of the tridiagonal matrix. On exit, if INFO = 0, the eigenvalues in ascending order. ⭐ sorted, as they should be.
E — is DOUBLE PRECISION array, dimension (N-1). On entry, the subdiagonal elements of the tridiagonal matrix. On exit, E has been destroyed. 🫠 rip E, you served your purpose.
Z — is COMPLEX*16 array, dimension (LDZ,N). On entry, if COMPZ = 'V', then Z contains the unitary matrix used in the reduction to tridiagonal form. On exit, if INFO = 0, then if COMPZ = 'V', Z contains the orthonormal eigenvectors of the original Hermitian matrix, and if COMPZ = 'I', Z contains the orthonormal eigenvectors of the symmetric tridiagonal matrix. If COMPZ = 'N', then Z is not referenced. (it's just there, chilling. 🙈)
LDZ — is INTEGER. The leading dimension of the array Z. LDZ >= 1. If eigenvectors are desired, then LDZ >= max(1,N).
WORK — is COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK

`LWORK`

Okay so LWORK is an INTEGER — it's literally the dimension of the WORK array, bestie. 💖 No cap.

If COMPZ = 'N' or 'I', or if N <= 1, then LWORK must be at least 1. Periodt.
If COMPZ = 'V' and N > 1, then LWORK must be at least N*N. Slay.
Note: for COMPZ = 'V', if N is less than or equal to the minimum divide size, usually 25, then LWORK need only be 1. ✨ It's giving minimal effort, and that's valid.

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA. 🫶 Iykyk.

`RWORK`

RWORK is DOUBLE PRECISION array, dimension (MAX(1,LRWORK)). On exit, if INFO = 0, RWORK(1) returns the optimal LRWORK. 👑

`LRWORK`

LRWORK is INTEGER. The dimension of the array RWORK.

If COMPZ = 'N' or N <= 1, LRWORK must be at least 1.
If COMPZ = 'V' and N > 1, LRWORK must be at least

1 + 3*N + 2*N*lg N + 4*N**2 ,

where lg( N ) = smallest integer k such that 2**k >= N.

If COMPZ = 'I' and N > 1, LRWORK must be at least

1 + 4*N + 2*N**2 .

Note that for COMPZ = 'I' or 'V', then if N is less than or equal to the minimum divide size, usually 25, then LRWORK need only be max(1,2*(N-1)). 🦋

If LRWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA. 💅

`IWORK`

IWORK is INTEGER array, dimension (MAX(1,LIWORK)). On exit, if INFO = 0, IWORK(1) returns the optimal LIWORK. 🌸

`LIWORK`

LIWORK is INTEGER. The dimension of the array IWORK.

If COMPZ = 'N' or N <= 1, LIWORK must be at least 1.
If COMPZ = 'V' or N > 1, LIWORK must be at least

6 + 6*N + 5*N*lg N.

If COMPZ = 'I' or N > 1, LIWORK must be at least

3 + 5*N .

Note that for COMPZ = 'I' or 'V', then if N is less than or equal to the minimum divide size, usually 25, then LIWORK need only be 1. 🧚

If LIWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA. 💜

`INFO`

INFO is INTEGER

= 0: successful exit. 🎉
< 0: if INFO = -i, the i-th argument had an illegal value. 😭
> 0: The algorithm failed to compute an eigenvalue while working on the submatrix lying in rows and columns INFO/(N+1) through mod(INFO,N+1). 💀

Author

Univ. of Tennessee Univ. of California Berkeley Univ. of Colorado Denver NAG Ltd.

Contributors:

Jeff Rutter, Computer Science Division, University of California at Berkeley, USA

`zstegr`

subroutine zstegr (character JOBZ, character RANGE, integer N, double precision, dimension( * ) D, double precision, dimension( * ) E, double precision VL, double precision VU, integer IL, integer IU, double precision ABSTOL, integer M, double precision, dimension( * ) W, complex*16, dimension( ldz, * ) Z, integer LDZ, integer, dimension( * ) ISUPPZ, double precision, dimension( * ) WORK, integer LWORK, integer, dimension( * ) IWORK, integer LIWORK, integer INFO)

`ZSTEGR`

Purpose:

ZSTEGR computes selected eigenvalues and, optionally, eigenvectors of a real symmetric tridiagonal matrix T. Any such unreduced matrix has a well defined set of pairwise different real eigenvalues, the corresponding real eigenvectors are pairwise orthogonal. ✨

The spectrum may be computed either completely or partially by specifying either an interval (VL,VU] or a range of indices IL:IU for the desired eigenvalues. 👑

ZSTEGR is a compatibility wrapper around the improved ZSTEMR routine. See ZSTEMR for further details. 🫶

One important change is that the ABSTOL parameter no longer provides any benefit and hence is no longer used. 💅

Note : ZSTEGR and ZSTEMR work only on machines which follow IEEE-754 floating-point standard in their handling of infinities and NaNs. Normal execution may create these exceptiona values and hence may abort due to a floating point exception in environments which do not conform to the IEEE-754 standard. 🌈

Parameters

JOBZ JOBZ is CHARACTER*1

= 'N': Compute eigenvalues only;
= 'V': Compute eigenvalues and eigenvectors. 💖

RANGE RANGE is CHARACTER*1

= 'A': all eigenvalues will be found.
= 'V': all eigenvalues in the half-open interval (VL,VU] will be found.
= 'I': the IL-th through IU-th eigenvalues will be found. 🎀

N N is INTEGER The order of the matrix. N >= 0. 🌸

D D is DOUBLE PRECISION array, dimension (N) On entry, the N diagonal elements of the tridiagonal matrix T. On exit, D is overwritten. 🦋

E E is DOUBLE PRECISION array, dimension (N) On entry, the (N-1) subdiagonal elements of the tridiagonal matrix T in elements 1 to N-1 of E. E(N) need not be set on input, but is used internally as workspace. On exit, E is overwritten. 🧚

VL VL is DOUBLE PRECISION If RANGE='V', the lower bound of the interval to be searched for eigenvalues. VL < VU. Not referenced if RANGE = 'A' or 'I'. 💜

VU VU is DOUBLE PRECISION If RANGE='V', the upper bound of the interval to be searched for eigenvalues. VL < VU. Not referenced if RANGE = 'A' or 'I'. 💙

IL IL is INTEGER If RANGE='I', the index of the smallest eigenvalue to be returned. 1 <= IL <= IU <= N, if N > 0. Not referenced if RANGE = 'A' or 'V'. 💚

IU IU is INTEGER If RANGE='I', the index of the largest eigenvalue to be returned. 1 <= IL <= IU <= N, if N > 0. Not referenced if RANGE = 'A' or 'V'. 💛

ABSTOL ABSTOL is DOUBLE PRECISION Unused. Was the absolute error tolerance for the eigenvalues/eigenvectors in previous versions. 🙈

M M is INTEGER The total number of eigenvalues found. 0 <= M <= N. If RANGE = 'A', M = N, and if RANGE = 'I', M = IU-IL+1. 🔥

W W is DOUBLE PRECISION array, dimension (N) The first M elements contain the selected eigenvalues in ascending order. ⭐

Z Z is COMPLEX*16 array, dimension (LDZ, max(1,M) ) If JOBZ = 'V', and if INFO = 0, then the first M columns of Z contain the orthonormal eigenvectors of the matrix T corresponding to the selected eigenvalues, with the i-th column of Z holding the eigenvector associated with W(i). If JOBZ = 'N', then Z is not referenced. Note: the user must ensure that at least max(1,M) columns are supplied in the array Z; if RANGE = 'V', the exact value of M is not known in advance and an upper bound must be used. Supplying N columns is always safe. 💎

LDZ LDZ is INTEGER The leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', then LDZ >= max(1,N). 🌟

ISUPPZ ISUPPZ is INTEGER array, dimension ( 2*max(1,M) ) The support of the eigenvectors in Z, i.e., the indices indicating the nonzero elements in Z. The i-th computed eigenvector is nonzero only in elements ISUPPZ( 2*i-1 ) through ISUPPZ( 2*i ). This is relevant in the case when the matrix is split. ISUPPZ is only accessed when JOBZ is 'V' and N > 0. 🎯

WORK WORK is DOUBLE PRECISION array, dimension (LWORK) On exit, if INFO = 0, WORK(1) returns the optimal (and minimal) LWORK. ⚡

LWORK LWORK is INTEGER The dimension of the array WORK. LWORK >= max(1,18*N) if JOBZ = 'V', and LWORK >= max(1,12*N) if JOBZ = 'N'. If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. 🔧

IWORK IWORK is INTEGER array, dimension (LIWORK) On exit, if INFO = 0, IWORK(1) returns the optimal LIWORK. 🛠️

LIWORK LIWORK is INTEGER The dimension of the array IWORK. LIWORK >= max(1,10*N) if the eigenvectors are desired, and LIWORK >= max(1,8*N) if only the eigenvalues are to be computed. If LIWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the IWORK array, returns this value as the first entry of the IWORK array, and no error message related to LIWORK is issued by XERBLA. 🧰

INFO

On exit, INFO spills the tea:

= 0: successful exit, we ate 💅
< 0: if INFO = -i, the i-th argument had an illegal value 🙈
> 0: if INFO = 1X, internal error in DLARRE; if INFO = 2X, internal error in ZLARRV. Here, the digit X = ABS( IINFO ) < 10, where IINFO is the nonzero error code returned by DLARRE or ZLARRV, respectively 💀

Author 🫶

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

Contributors 💜

Inderjit Dhillon, IBM Almaden, USA
Osni Marques, LBNL/NERSC, USA
Christof Voemel, LBNL/NERSC, USA

subroutine `zstein` 🌸

subroutine zstein (integer N, double precision, dimension( * ) D, double
    precision, dimension( * ) E, integer M, double precision, dimension( * )
    W, integer, dimension( * ) IBLOCK, integer, dimension( * ) ISPLIT,
    complex*16, dimension( ldz, * ) Z, integer LDZ, double precision,
    dimension( * ) WORK, integer, dimension( * ) IWORK, integer, dimension(
    * ) IFAIL, integer INFO)

`ZSTEIN` ✨

Purpose 🎀

ZSTEIN computes the eigenvectors of a real symmetric tridiagonal matrix T corresponding to specified eigenvalues, using inverse iteration.

The maximum number of iterations allowed for each eigenvector is specified by an internal parameter MAXITS (currently set to 5).

So here's the vibe: even though the eigenvectors are real, they get stored in a complex array, because that array might get passed along to ZUNMTR or ZUPMTR for back transformation to the eigenvectors of a complex Hermitian matrix that was reduced to tridiagonal form. Bestie, it's all connected 🔥

Parameters 🦋

N — N is INTEGER. The order of the matrix. N >= 0.
D — D is DOUBLE PRECISION array, dimension (N). The n diagonal elements of the tridiagonal matrix T.
E — E is DOUBLE PRECISION array, dimension (N-1). The (n-1) subdiagonal elements of the tridiagonal matrix T, stored in elements 1 to N-1.
M — M is INTEGER. The number of eigenvectors to be found. 0 <= M <= N.
W — W is DOUBLE PRECISION array, dimension (N). The first M elements of W contain the eigenvalues for which eigenvectors are to be computed. The eigenvalues should be grouped by split-off block and ordered from smallest to largest within the block. (The output array W from DSTEBZ with ORDER = 'B' is expected here.)
IBLOCK — IBLOCK is INTEGER array, dimension (N). The submatrix indices associated with the corresponding eigenvalues in W; IBLOCK(i)=1 if eigenvalue W(i) belongs to the first submatrix from the top, =2 if W(i) belongs to the second submatrix, etc. (The output array IBLOCK from DSTEBZ is expected here.)
ISPLIT — ISPLIT is INTEGER array, dimension (N). The splitting points, at which T breaks up into submatrices. The first submatrix consists of rows/columns 1 to ISPLIT( 1 ), the second of rows/columns ISPLIT( 1 )+1 through ISPLIT( 2 ), etc. (The output array ISPLIT from DSTEBZ is expected here.)
Z — Z is COMPLEX*16 array, dimension (LDZ, M). The computed eigenvectors. The eigenvector associated with the eigenvalue W(i) is stored in the i-th column of Z. Any vector which fails to converge is set to its current iterate after MAXITS iterations. The imaginary parts of the eigenvectors are set to zero.
LDZ — LDZ is INTEGER. The leading dimension of the array Z. LDZ >= max(1,N).
WORK — WORK is DOUBLE PRECISION array, dimension (5*N).
IWORK — IWORK is INTEGER array, dimension (N).
IFAIL — IFAIL is INTEGER array, dimension (M). On normal exit, all elements of IFAIL are zero. If one or more eigenvectors fail to converge after MAXITS iterations, then their indices are stored in array IFAIL.
INFO — INFO is INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, then i eigenvectors failed to converge in MAXITS iterations. Their indices are stored in array IFAIL.

Internal Parameters 🧚

MAXITS — INTEGER, default = 5. The maximum number of iterations performed.
EXTRA — INTEGER, default = 2. The number of iterations performed after norm growth criterion is satisfied, should be at least 1.

Author 🫶

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine `zstemr` 👑

subroutine zstemr (character JOBZ, character RANGE, integer N, double
    precision, dimension( * ) D, double precision, dimension( * ) E, double
    precision VL, double precision VU, integer IL, integer IU, integer M,
    double precision, dimension( * ) W, complex*16, dimension( ldz, * ) Z,
    integer LDZ, integer NZC, integer, dimension( * ) ISUPPZ, logical
    TRYRAC, double precision, dimension( * ) WORK, integer LWORK, integer,
    dimension( * ) IWORK, integer LIWORK, integer INFO)

`ZSTEMR` 🌈

Purpose 💖

ZSTEMR computes selected eigenvalues and, optionally, eigenvectors of a real symmetric tridiagonal matrix T. Any such unreduced matrix has a well defined set of pairwise different real eigenvalues, and the corresponding real eigenvectors are pairwise orthogonal.

The spectrum may be computed either completely or partially by specifying either an interval (VL,VU] or a range of indices IL:IU for the desired eigenvalues.

Depending on the number of desired eigenvalues, these are computed either by bisection or the dqds algorithm. Numerically orthogonal eigenvectors are computed by the use of various suitable L D L^T factorizations near clusters of close eigenvalues (referred to as RRRs, Relatively Robust Representations). An informal sketch of the algorithm follows.

For each unreduced block (submatrix) of T:

(a) Compute T - sigma I = L D L^T, so that L and D define all the wanted eigenvalues to high relative accuracy. This means that small relative changes in the entries of D and L cause only small relative changes in the eigenvalues and eigenvectors. The standard (unfactored) representation of the tridiagonal matrix T does not have this property in general.
(b) Compute the eigenvalues to suitable accuracy. If the eigenvectors are desired, the algorithm attains full accuracy of the computed eigenvalues only right before the corresponding vectors have to be computed, see steps c) and d).
(c) For each cluster of close eigenvalues, select a new shift close to the cluster, find a new factorization, and refine the shifted eigenvalues to suitable accuracy.
(d) For each eigenvalue with a large enough relative separation compute the corresponding eigenvector by forming a rank revealing twisted factorization. Go back to (c) for any clusters that remain.

For more details, see:

Inderjit S. Dhillon and Beresford N. Parlett: 'Multiple representations to compute orthogonal eigenvectors of symmetric tridiagonal matrices,' Linear Algebra and its Applications, 387(1), pp. 1-28, August 2004.
Inderjit Dhillon and Beresford Parlett: 'Orthogonal Eigenvectors and Relative Gaps,' SIAM Journal on Matrix Analysis and Applications, Vol. 25, 2004. Also LAPACK Working Note 154.
Inderjit Dhillon: 'A new O(n^2) algorithm for the symmetric tridiagonal eigenvalue/eigenvector problem', Computer Science Division Technical Report No. UCB/CSD-97-971, UC Berkeley, May 1997.

Further Details 🦋

ZSTEMR works only on machines which follow IEEE-754 floating-point standard in their handling of infinities and NaNs. This permits the use of efficient inner loops avoiding a check for zero divisors.
LAPACK routines can be used to reduce a complex Hermitean matrix to real symmetric tridiagonal form.

(Any complex Hermitean tridiagonal matrix has real values on its diagonal and potentially complex numbers on its off-diagonals. By applying a similarity transform with an appropriate diagonal matrix diag(1,e^{i \phy_1}, ... , e^{i \phy_{n-1}}), the complex Hermitean matrix can be transformed into a real symmetric matrix and complex arithmetic can be entirely avoided.)

While the eigenvectors of the real symmetric tridiagonal matrix are real, the eigenvectors of original complex Hermitean matrix have complex entries in general. Since LAPACK drivers overwrite the matrix data with the eigenvectors, ZSTEMR accepts complex workspace to facilitate interoperability with ZUNMTR or ZUPMTR.

Parameters 🎀

JOBZ — JOBZ is CHARACTER*1.
- = 'N': Compute eigenvalues only;
- = 'V': Compute eigenvalues and eigenvectors.
RANGE — RANGE is CHARACTER*1.
- = 'A': all eigenvalues will be found.
- = 'V': all eigenvalues in the half-open interval (VL,VU] will be found.
- = 'I': the IL-th through IU-th eigenvalues will be found.
N — N is INTEGER. The order of the matrix. N >= 0.
D — D is DOUBLE PRECISION array, dimension (N). On entry, the N diagonal elements of the tridiagonal matrix T. On exit, D is overwritten.
E — E is DOUBLE PRECISION array, dimension (N). On entry, the (N-1) subdiagonal elements of the tridiagonal matrix T in elements 1 to N-1 of E. E(N) need not be set on input, but is used internally as workspace. On exit, E is overwritten.
VL — VL is DOUBLE PRECISION. If RANGE='V', the lower bound of the interval to be searched for eigenvalues. VL < VU. Not referenced if RANGE = 'A' or 'I'.
VU — VU is DOUBLE PRECISION.
VU — VU is DOUBLE PRECISION. If RANGE='V', this is the upper bound of the interval we're out here searching for eigenvalues in. VL < VU. Not referenced if RANGE = 'A' or RANGE = 'I'. 💅
IL — IL is INTEGER. If RANGE='I', it's the index of the smallest eigenvalue to be returned. 1 <= IL <= IU <= N, if N > 0. Not referenced if RANGE = 'A' or 'V'. 🦋
IU — IU is INTEGER. If RANGE='I', it's the index of the largest eigenvalue to be returned. 1 <= IL <= IU <= N, if N > 0. Not referenced if RANGE = 'A' or 'V'. 🌸
M — M is INTEGER. The total number of eigenvalues found. 0 <= M <= N. If RANGE = 'A', then M = N, and if RANGE = 'I', then M = IU-IL+1. bestie the math is mathing ✨
W — W is DOUBLE PRECISION array, dimension (N). The first M elements hold the selected eigenvalues in ascending order. clean, sorted, organized — she's giving type-A main character energy 👑
Z — Z is COMPLEX*16 array, dimension (LDZ, max(1,M) ). If JOBZ = 'V', and if INFO = 0, then the first M columns of Z contain the orthonormal eigenvectors of the matrix T corresponding to the selected eigenvalues, with the i-th column of Z holding the eigenvector associated with W(i). If JOBZ = 'N', then Z is not referenced. Note: the user must ensure that at least max(1,M) columns are supplied in the array Z; if RANGE = 'V', the exact value of M is not known in advance and can be computed with a workspace query by setting NZC = -1, see below. 😭 (yes you have to actually give her enough space, she will NOT be squeezing into a too-small array)
LDZ — LDZ is INTEGER. The leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', then LDZ >= max(1,N). 📏
NZC — NZC is INTEGER. The number of eigenvectors to be held in the array Z. If RANGE = 'A', then NZC >= max(1,N). If RANGE = 'V', then NZC >= the number of eigenvalues in (VL,VU]. If RANGE = 'I', then NZC >= IU-IL+1. If NZC = -1, then a workspace query is assumed; the routine calculates the number of columns of the array Z that are needed to hold the eigenvectors. This value is returned as the first entry of the Z array, and no error message related to NZC is issued by XERBLA. 🎀
ISUPPZ — ISUPPZ is INTEGER array, dimension ( 2*max(1,M) ). The support of the eigenvectors in Z, i.e., the indices indicating the nonzero elements in Z. The i-th computed eigenvector is nonzero only in elements ISUPPZ( 2*i-1 ) through ISUPPZ( 2*i ). This is relevant in the case when the matrix is split. ISUPPZ is only accessed when JOBZ is 'V' and N > 0. 🔍
TRYRAC — TRYRAC is LOGICAL. If TRYRAC = .TRUE., it indicates that the code should check whether the tridiagonal matrix defines its eigenvalues to high relative accuracy. If so, the code uses relative-accuracy preserving algorithms that might be (a bit) slower depending on the matrix. If the matrix does not define its eigenvalues to high relative accuracy, the code can uses possibly faster algorithms. If TRYRAC = .FALSE., the code is not required to guarantee relatively accurate eigenvalues and can use the fastest possible techniques. On exit, a .TRUE. TRYRAC will be set to .FALSE. if the matrix does not define its eigenvalues to high relative accuracy. 💀 (yes it can flip itself on you, that's just how it is)
WORK — WORK is DOUBLE PRECISION array, dimension (LWORK). On exit, if INFO = 0, WORK(1) returns the optimal (and minimal) LWORK. 🛠️
LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= max(1,18*N) if JOBZ = 'V', and LWORK >= max(1,12*N) if JOBZ = 'N'. If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. ✨
IWORK — IWORK is INTEGER array, dimension (LIWORK). On exit, if INFO = 0, IWORK(1) returns the optimal LIWORK. 🧺
LIWORK — LIWORK is INTEGER. The dimension of the array IWORK. LIWORK >= max(1,10*N) if the eigenvectors are desired, and LIWORK >= max(1,8*N) if only the eigenvalues are to be computed. If LIWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the IWORK array, returns this value as the first entry of the IWORK array, and no error message related to LIWORK is issued by XERBLA. 🌈
INFO — INFO is INTEGER. On exit, INFO is:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 🙈
- > 0: if INFO = 1X, internal error in DLARRE, if INFO = 2X, internal error in ZLARRV. Here, the digit X = ABS( IINFO ) < 10, where IINFO is the nonzero error code returned by DLARRE or ZLARRV, respectively. 💀

Author ✍️

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Contributors: 🫶

Beresford Parlett, University of California, Berkeley, USA Jim Demmel, University of California, Berkeley, USA Inderjit Dhillon, University of Texas, Austin, USA Osni Marques, LBNL/NERSC, USA Christof Voemel, University of California, Berkeley, USA

subroutine `zsteqr` (character COMPZ, integer N, double precision, dimension( * ) D, double precision, dimension( * ) E, complex16, dimension( ldz, ) Z, integer LDZ, double precision, dimension( * ) WORK, integer INFO)

ZSTEQR

Purpose: 💫

ZSTEQR computes all eigenvalues and, optionally, eigenvectors of a symmetric tridiagonal matrix using the implicit QL or QR method. The eigenvectors of a full or band complex Hermitian matrix can also be found if ZHETRD or ZHPTRD or ZHBTRD has been used to reduce this matrix to tridiagonal form. she's the glow-up at the end of the pipeline, no cap 🦋

Parameters 📋

COMPZ — COMPZ is CHARACTER*1.
- = 'N': Compute eigenvalues only.
- = 'V': Compute eigenvalues and eigenvectors of the original Hermitian matrix. On entry, Z must contain the unitary matrix used to reduce the original matrix to tridiagonal form.
- = 'I': Compute eigenvalues and eigenvectors of the tridiagonal matrix. Z is initialized to the identity matrix.
N — N is INTEGER. The order of the matrix. N >= 0. 🔢
D — D is DOUBLE PRECISION array, dimension (N). On entry, the diagonal elements of the tridiagonal matrix. On exit, if INFO = 0, the eigenvalues in ascending order. 👑
E — E is DOUBLE PRECISION array, dimension (N-1). On entry, the (n-1) subdiagonal elements of the tridiagonal matrix. On exit, E has been destroyed. 💀 rip
Z — Z is COMPLEX*16 array, dimension (LDZ, N). On entry, if COMPZ = 'V', then Z contains the unitary matrix used in the reduction to tridiagonal form. On exit, if INFO = 0, then if COMPZ = 'V', Z contains the orthonormal eigenvectors of the original Hermitian matrix, and if COMPZ = 'I', Z contains the orthonormal eigenvectors of the symmetric tridiagonal matrix. If COMPZ = 'N', then Z is not referenced. ✨
LDZ — LDZ is INTEGER. The leading dimension of the array Z. LDZ >= 1, and if eigenvectors are desired, then LDZ >= max(1,N). 📐
WORK — WORK is DOUBLE PRECISION array, dimension (max(1,2*N-2)). If COMPZ = 'N', then WORK is not referenced. 🛠️
INFO — INFO is INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: the algorithm has failed to find all the eigenvalues in a total of 30*N iterations; if INFO = i, then i elements of E have not converged to zero; on exit, D and E contain the elements of a symmetric tridiagonal matrix which is unitarily similar to the original matrix. 😭 it tried its best

Author ✍️

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

subroutine `ztbcon` (character NORM, character UPLO, character DIAG, integer N, integer KD, complex16, dimension( ldab, ) AB, integer LDAB, double precision RCOND, complex16, dimension( ) WORK, double precision, dimension( * ) RWORK, integer INFO)

ZTBCON

Purpose: 💫

ZTBCON estimates the reciprocal of the condition number of a triangular band matrix A, in either the 1-norm or the infinity-norm.

The norm of A is computed and an estimate is obtained for norm(inv(A)), then the reciprocal of the condition number is computed as

   RCOND = 1 / ( norm(A) * norm(inv(A)) ).

like, how shaky is this matrix actually? vibe check incoming 🎀

Parameters 📋

NORM — NORM is CHARACTER*1. Specifies whether the 1-norm condition number or the infinity-norm condition number is required:
- = '1' or 'O': 1-norm;
- = 'I': Infinity-norm.
UPLO — UPLO is CHARACTER*1.
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
DIAG — DIAG is CHARACTER*1.
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — N is INTEGER. The order of the matrix A. N >= 0. 🔢
KD — KD is INTEGER. The number of superdiagonals or subdiagonals of the triangular band matrix A. KD >= 0. 📏
AB —
AB — bestie, this one is a COMPLEX*16 array, dimension (LDAB,N). It's the upper or lower triangular band matrix A, chillin' in the first kd+1 rows of the array. The j-th column of A lives in the j-th column of the array AB like this:
- if UPLO = 'U', then AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
- if UPLO = 'L', then AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).

And if DIAG = 'U', the diagonal elements of A are not referenced at all and are just assumed to be 1. iconic behavior honestly. 💅

LDAB — it's an INTEGER, the leading dimension of the array AB. Rule of the land: LDAB >= KD+1.
RCOND — a DOUBLE PRECISION, the reciprocal of the condition number of the matrix A, computed as RCOND = 1/(norm(A) * norm(inv(A))). math girlies stay winning. ✨
WORK — COMPLEX*16 array, dimension (2*N).
RWORK — DOUBLE PRECISION array, dimension (N).
INFO — INTEGER, the vibe check:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 😭

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

`subroutine ztbrfs` (character UPLO, character TRANS, character DIAG, integer N, integer KD, integer NRHS, complex16, dimension( ldab, ) AB, integer LDAB, complex16, dimension( ldb, ) B, integer LDB, complex16, dimension( ldx, ) X, integer LDX, double precision, dimension( * ) FERR, double precision, dimension( * ) BERR, complex16, dimension( ) WORK, double precision, dimension( * ) RWORK, integer INFO)

ZTBRFS 🌸

Purpose:

ZTBRFS hands you error bounds and backward error estimates for the solution to a system of linear equations rocking a triangular band coefficient matrix. 🎀

Real talk though: the solution matrix X must already be computed by ZTBTRS or some other means before you walk in here. And ZTBRFS does not do iterative refinement, because honestly doing so cannot improve the backward error. no cap.

Parameters

UPLO — CHARACTER*1:
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
TRANS — CHARACTER*1, specifies the form of the system of equations:
- = 'N': A * X = B (No transpose)
- = 'T': A**T * X = B (Transpose)
- = 'C': A**H * X = B (Conjugate transpose)
DIAG — CHARACTER*1:
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — INTEGER, the order of the matrix A. N >= 0.
KD — INTEGER, the number of superdiagonals or subdiagonals of the triangular band matrix A. KD >= 0.
NRHS — INTEGER, the number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >= 0.
AB — COMPLEX*16 array, dimension (LDAB,N). The upper or lower triangular band matrix A, stored in the first kd+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:
- if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
- if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).

If DIAG = 'U', the diagonal elements of A are not referenced and are assumed to be 1.

LDAB — INTEGER, the leading dimension of the array AB. LDAB >= KD+1.
B — COMPLEX*16 array, dimension (LDB,NRHS). The right hand side matrix B.
LDB — INTEGER, the leading dimension of the array B. LDB >= max(1,N).
X — COMPLEX*16 array, dimension (LDX,NRHS). The solution matrix X.
LDX — INTEGER, the leading dimension of the array X. LDX >= max(1,N).
FERR — DOUBLE PRECISION array, dimension (NRHS). The estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), then FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error. 💖
BERR — DOUBLE PRECISION array, dimension (NRHS). The componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution).
WORK — COMPLEX*16 array, dimension (2*N).
RWORK — DOUBLE PRECISION array, dimension (N).
INFO — INTEGER:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 😭

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

`subroutine ztbtrs` (character UPLO, character TRANS, character DIAG, integer N, integer KD, integer NRHS, complex16, dimension( ldab, ) AB, integer LDAB, complex16, dimension( ldb, ) B, integer LDB, integer INFO)

ZTBTRS 🦋

Purpose:

ZTBTRS solves a triangular system of the form

A * X = B,  A**T * X = B,  or  A**H * X = B,

where A is a triangular band matrix of order N, and B is an N-by-NRHS matrix. A check is made to verify that A is nonsingular. 👑

Parameters

UPLO — CHARACTER*1:
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
TRANS — CHARACTER*1, specifies the form of the system of equations:
- = 'N': A * X = B (No transpose)
- = 'T': A**T * X = B (Transpose)
- = 'C': A**H * X = B (Conjugate transpose)
DIAG — CHARACTER*1:
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — INTEGER, the order of the matrix A. N >= 0.
KD — INTEGER, the number of superdiagonals or subdiagonals of the triangular band matrix A. KD >= 0.
NRHS — INTEGER, the number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
AB — COMPLEX*16 array, dimension (LDAB,N). The upper or lower triangular band matrix A, stored in the first kd+1 rows of AB. The j-th column of A is stored in the j-th column of the array AB as follows:
- if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
- if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).

If DIAG = 'U', the diagonal elements of A are not referenced and are assumed to be 1.

LDAB — INTEGER, the leading dimension of the array AB. LDAB >= KD+1.
B — COMPLEX*16 array, dimension (LDB,NRHS). On entry, the right hand side matrix B. On exit, if INFO = 0, the solution matrix X. ✨
LDB — INTEGER, the leading dimension of the array B. LDB >= max(1,N).
INFO — INTEGER:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 😭
- > 0: if INFO = i, the i-th diagonal element of A is zero, indicating that the matrix is singular and the solutions X have not been computed. 💀

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

`subroutine ztfsm` (character TRANSR, character SIDE, character UPLO, character TRANS, character DIAG, integer M, integer N, complex16 ALPHA, complex16, dimension( 0: * ) A, complex16, dimension( 0: ldb-1, 0: ) B, integer LDB)

ZTFSM solves a matrix equation (one operand is a triangular matrix in RFP format). 🌈

Purpose:

Level 3 BLAS like routine for A in RFP Format. 🎀

ZTFSM solves the matrix equation

op( A )*X = alpha*B  or  X*op( A ) = alpha*B

where alpha is a scalar, X and B are m by n matrices, A is a unit, or non-unit, upper or lower triangular matrix and op( A ) is one of

op( A ) = A   or   op( A ) = A**H.

A is in Rectangular Full Packed (RFP) Format. 💅

The matrix X is overwritten on B.

Parameters

TRANSR — CHARACTER*1:
- = 'N': The Normal Form of RFP A is stored;
- = 'C': The Conjugate-transpose Form of RFP A is stored.
SIDE — CHARACTER*1. On entry, SIDE specifies whether op( A ) appears on the left or right of X as follows:
- SIDE = 'L' or 'l' → op( A )*X = alpha*B.
- SIDE = 'R' or 'r' → X*op( A ) = alpha*B.

Unchanged on exit.

UPLO — CHARACTER*1. On entry, UPLO specifies whether the RFP matrix A came from an upper or lower triangular matrix as follows:
- UPLO = 'U' or 'u' → RFP A came from an upper triangular matrix
- UPLO = 'L' or 'l' → RFP A came from a lower triangular matrix

Unchanged on exit.

TRANS — CHARACTER*1. On entry, TRANS specifies the form of op( A ) to be used in the matrix multiplication as follows:
- TRANS = 'N' or 'n' → op( A ) = A.
- TRANS = 'C' or 'c' → op( A ) = conjg( A' ).

Unchanged on exit.

DIAG — CHARACTER*1. On entry, DIAG specifies whether or not RFP A is unit triangular as follows:
- DIAG = 'U' or 'u' → A is assumed to be unit triangular.
= 'N' or 'n' — A is not assumed to be unit triangular.
Unchanged on exit. 💖

M — INTEGER. On entry, M is the number of rows of B. M must be at least zero. Unchanged on exit. no cap.
N — INTEGER. On entry, N is the number of columns of B. N must be at least zero. Unchanged on exit. slay.
ALPHA — COMPLEX*16. On entry, ALPHA is the scalar alpha. The tea ☕: when alpha is zero, A is not referenced and B doesn't even need to be set before entry. Unchanged on exit. it's giving "we're not even looking at A bestie" 💅
A — COMPLEX*16 array, dimension (N*(N+1)/2). NT = N*(N+1)/2. On entry, the matrix A in RFP Format. RFP Format is described by TRANSR, UPLO and N as follows: if TRANSR='N' then RFP A is (0:N,0:K-1) when N is even; K=N/2. RFP A is (0:N-1,0:K) when N is odd; K=N/2. If TRANSR = 'C' then RFP is the Conjugate-transpose of RFP A as defined when TRANSR = 'N'. The contents of RFP A are defined by UPLO as follows: if UPLO = 'U' the RFP A contains the NT elements of upper packed A either in normal or conjugate-transpose Format. If UPLO = 'L' the RFP A contains the NT elements of lower packed A either in normal or conjugate-transpose Format. The LDA of RFP A is (N+1)/2 when TRANSR = 'C'. When TRANSR is 'N' the LDA is N+1 when N is even and is N when is odd. See the Note below for more details. Unchanged on exit. 🌸
B — COMPLEX*16 array, dimension (LDB,N). Before entry, the leading m by n part of the array B must contain the right-hand side matrix B, and on exit is overwritten by the solution matrix X. glow-up arc ✨
LDB — INTEGER. On entry, LDB specifies the first dimension of B as declared in the calling (sub) program. LDB must be at least max( 1, m ). Unchanged on exit.

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details 🔍

okay so first we consider Standard Packed Format when N is even. We give an example where N = 6. 🫶

    AP is Upper             AP is Lower

  00 01 02 03 04 05       00
     11 12 13 14 15       10 11
        22 23 24 25       20 21 22
           33 34 35       30 31 32 33
              44 45       40 41 42 43 44
                 55       50 51 52 53 54 55

Let TRANSR = 'N'. RFP holds AP as follows: for UPLO = 'U' the upper trapezoid A(0:5,0:2) consists of the last three columns of AP upper. The lower triangle A(4:6,0:2) consists of conjugate-transpose of the first three columns of AP upper. For UPLO = 'L' the lower trapezoid A(1:6,0:2) consists of the first three columns of AP lower. The upper triangle A(0:2,0:2) consists of conjugate-transpose of the last three columns of AP lower. To denote conjugate we place -- above the element. This covers the case N even and TRANSR = 'N'. 🦋

        RFP A                   RFP A

                               -- -- --
       03 04 05                33 43 53
                                  -- --
       13 14 15                00 44 54
                                     --
       23 24 25                10 11 55

       33 34 35                20 21 22
       --
       00 44 45                30 31 32
       -- --
       01 11 55                40 41 42
       -- -- --
       02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets: 💫

          RFP A                   RFP A

    -- -- -- --                -- -- -- -- -- --
    03 13 23 33 00 01 02    33 00 10 20 30 40 50
    -- -- -- -- --                -- -- -- -- --
    04 14 24 34 44 11 12    43 44 11 21 31 41 51
    -- -- -- -- -- --                -- -- -- --
    05 15 25 35 45 55 22    53 54 55 22 32 42 52

We next consider Standard Packed Format when N is odd. We give an example where N = 5. 🎀

    AP is Upper                 AP is Lower

  00 01 02 03 04              00
     11 12 13 14              10 11
        22 23 24              20 21 22
           33 34              30 31 32 33
              44              40 41 42 43 44

Let TRANSR = 'N'. RFP holds AP as follows: for UPLO = 'U' the upper trapezoid A(0:4,0:2) consists of the last three columns of AP upper. The lower triangle A(3:4,0:1) consists of conjugate-transpose of the first two columns of AP upper. For UPLO = 'L' the lower trapezoid A(0:4,0:2) consists of the first three columns of AP lower. The upper triangle A(0:1,1:2) consists of conjugate-transpose of the last two columns of AP lower. To denote conjugate we place -- above the element. This covers the case N odd and TRANSR = 'N'. 🌈

        RFP A                   RFP A

                                  -- --
       02 03 04                00 33 43
                                     --
       12 13 14                10 11 44

       22 23 24                20 21 22
       --
       00 33 34                30 31 32
       -- --
       01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets: ⭐

          RFP A                   RFP A

    -- -- --                   -- -- -- -- -- --
    02 12 22 00 01             00 10 20 30 40 50
    -- -- -- --                   -- -- -- -- --
    03 13 23 33 11             33 11 21 31 41 51
    -- -- -- -- --                   -- -- -- --
    04 14 24 34 44             43 44 22 32 42 52

✨ subroutine ztftri (character TRANSR, character UPLO, character DIAG, integer N, complex16, dimension( 0: ) A, integer INFO) ✨

ZTFTRI

🎯 Purpose 🎯

ZTFTRI computes the inverse of a triangular matrix A stored in RFP format.

This is a Level 3 BLAS version of the algorithm. it's giving main character energy fr fr 💅

🧮 Parameters 🧮

TRANSR — CHARACTER*1
- = 'N': The Normal TRANSR of RFP A is stored;
- = 'C': The Conjugate-transpose TRANSR of RFP A is stored.
UPLO — CHARACTER*1
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
DIAG — CHARACTER*1
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — INTEGER. The order of the matrix A. N >= 0.
A — COMPLEX*16 array, dimension ( N*(N+1)/2 ). On entry, the triangular matrix A in RFP format. RFP format is described by TRANSR, UPLO, and N as follows: If TRANSR = 'N' then RFP A is (0:N,0:k-1) when N is even; k=N/2. RFP A is (0:N-1,0:k) when N is odd; k=N/2. IF TRANSR = 'C' then RFP is the Conjugate-transpose of RFP A as defined when TRANSR = 'N'. The contents of RFP A are defined by UPLO as follows: If UPLO = 'U' the RFP A contains the nt elements of upper packed A; If UPLO = 'L' the RFP A contains the nt elements of lower packed A. The LDA of RFP A is (N+1)/2 when TRANSR = 'C'. When TRANSR is 'N' the LDA is N+1 when N is even and N is odd. See the Note below for more details. 💜

On exit, the (triangular) inverse of the original matrix, in the same storage format. glow-up complete 😌

INFO — INTEGER
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 🙈
- > 0: if INFO = i, A(i,i) is exactly zero. The triangular matrix is singular and its inverse can not be computed. 💀

bestie. if INFO > 0 that matrix said "no" and there is literally nothing we can do about it. singular means singular.

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details 🔍

We first consider Standard Packed Format when N is even. We give an example where N = 6. 🍓

    AP is Upper             AP is Lower

  00 01 02 03 04 05       00
     11 12 13 14 15       10 11
        22 23 24 25       20 21 22
           33 34 35       30 31 32 33
              44 45       40 41 42 43 44
                 55       50 51 52 53 54 55

        RFP A                   RFP A

                               -- -- --
       03 04 05                33 43 53
                                  -- --
       13 14 15                00 44 54
                                     --
       23 24 25                10 11 55

       33 34 35                20 21 22
       --
       00 44 45                30 31 32
       -- --
       01 11 55                40 41 42
       -- -- --
       02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets: 🧚

          RFP A                   RFP A

                -- -- -- --                -- -- -- -- -- --
                03 13 23 33 00 01 02    33 00 10 20 30 40 50
                -- -- -- -- --                -- -- -- -- --
                04 14 24 34 44 11 12    43 44 11 21 31 41 51
                -- -- -- -- -- --                -- -- -- --
                05 15 25 35 45 55 22    53 54 55 22 32 42 52

okay bestie, next up: Standard Packed Format but when N is odd. we're giving an example where N = 5. 💅

                AP is Upper                 AP is Lower

              00 01 02 03 04              00
                 11 12 13 14              10 11
                    22 23 24              20 21 22
                       33 34              30 31 32 33
                          44              40 41 42 43 44

Let TRANSR = 'N'. RFP holds AP like this:

For UPLO = 'U' the upper trapezoid A(0:4,0:2) is made of the last three columns of AP upper. The lower triangle A(3:4,0:1) is made of conjugate-transpose of the first two columns of AP upper.
For UPLO = 'L' the lower trapezoid A(0:4,0:2) is made of the first three columns of AP lower. The upper triangle A(0:1,1:2) is made of conjugate-transpose of the last two columns of AP lower.

To show a conjugate we put -- above the element. This covers the case N odd and TRANSR = 'N'.

                    RFP A                   RFP A

                                              -- --
                   02 03 04                00 33 43
                                                 --
                   12 13 14                10 11 44

                   22 23 24                20 21 22
                   --
                   00 33 34                30 31 32
                   -- --
                   01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is literally just the conjugate-transpose of RFP A above, no cap. So you get:

                      RFP A                   RFP A

                -- -- --                   -- -- -- -- -- --
                02 12 22 00 01             00 10 20 30 40 50
                -- -- -- --                   -- -- -- -- --
                03 13 23 33 11             33 11 21 31 41 51
                -- -- -- -- --                   -- -- -- --
                04 14 24 34 44             43 44 22 32 42 52

subroutine ztfttp ✨

subroutine ztfttp (character TRANSR, character UPLO, integer N, complex*16,
    dimension( 0: * ) ARF, complex*16, dimension( 0: * ) AP, integer INFO)

ZTFTTP copies a triangular matrix from the rectangular full packed format (TF) to the standard packed format (TP). 🦋

Purpose 💖

ZTFTTP copies a triangular matrix A from rectangular full packed format (TF) to standard packed format (TP).

Parameters 🎀

TRANSR — TRANSR is CHARACTER*1. It's giving format selector:
- = 'N': ARF is in Normal format;
- = 'C': ARF is in Conjugate-transpose format;
UPLO — UPLO is CHARACTER*1:
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
N — N is INTEGER. The order of the matrix A. N >= 0.
ARF — ARF is COMPLEX*16 array, dimension ( N*(N+1)/2 ). On entry, the upper or lower triangular matrix A stored in RFP format. For a further discussion see Notes below. 👀
AP — AP is COMPLEX*16 array, dimension ( N*(N+1)/2 ). On exit, the upper or lower triangular matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.
INFO — INFO is INTEGER:
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value 💀

Author 👑

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

Further Details 🌈

We first consider Standard Packed Format when N is even. We give an example where N = 6.

    AP is Upper             AP is Lower

 00 01 02 03 04 05       00
    11 12 13 14 15       10 11
       22 23 24 25       20 21 22
          33 34 35       30 31 32 33
             44 45       40 41 42 43 44
                55       50 51 52 53 54 55

Let TRANSR = 'N'. RFP holds AP like this:

For UPLO = 'U' the upper trapezoid A(0:5,0:2) is made of the last three columns of AP upper. The lower triangle A(4:6,0:2) is made of conjugate-transpose of the first three columns of AP upper.
For UPLO = 'L' the lower trapezoid A(1:6,0:2) is made of the first three columns of AP lower. The upper triangle A(0:2,0:2) is made of conjugate-transpose of the last three columns of AP lower.

To show a conjugate we put -- above the element. This covers the case N even and TRANSR = 'N'.

       RFP A                   RFP A

                              -- -- --
      03 04 05                33 43 53
                                 -- --
      13 14 15                00 44 54
                                    --
      23 24 25                10 11 55

      33 34 35                20 21 22
      --
      00 44 45                30 31 32
      -- --
      01 11 55                40 41 42
      -- -- --
      02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

         RFP A                   RFP A

   -- -- -- --                -- -- -- -- -- --
   03 13 23 33 00 01 02    33 00 10 20 30 40 50
   -- -- -- -- --                -- -- -- -- --
   04 14 24 34 44 11 12    43 44 11 21 31 41 51
   -- -- -- -- -- --                -- -- -- -- --
   05 15 25 35 45 55 22    53 54 55 22 32 42 52

We next consider Standard Packed Format when N is odd. We give an example where N = 5.

   AP is Upper                 AP is Lower

 00 01 02 03 04              00
    11 12 13 14              10 11
       22 23 24              20 21 22
          33 34              30 31 32 33
             44              40 41 42 43 44

Let TRANSR = 'N'. RFP holds AP like this:

For UPLO = 'U' the upper trapezoid A(0:4,0:2) is made of the last three columns of AP upper. The lower triangle A(3:4,0:1) is made of conjugate-transpose of the first two columns of AP upper.
For UPLO = 'L' the lower trapezoid A(0:4,0:2) is made of the first three columns of AP lower. The upper triangle A(0:1,1:2) is made of conjugate-transpose of the last two columns of AP lower.

To show a conjugate we put -- above the element. This covers the case N odd and TRANSR = 'N'.

       RFP A                   RFP A

                                 -- --
      02 03 04                00 33 43
                                    --
      12 13 14                10 11 44

      22 23 24                20 21 22
      --
      00 33 34                30 31 32
      -- --
      01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

         RFP A                   RFP A

   -- -- --                   -- -- -- -- -- --
   02 12 22 00 01             00 10 20 30 40 50
   -- -- -- --                   -- -- -- -- --
   03 13 23 33 11             33 11 21 31 41 51
   -- -- -- -- --                   -- -- -- --
   04 14 24 34 44             43 44 22 32 42 52

subroutine ztfttr 🌸

subroutine ztfttr (character TRANSR, character UPLO, integer N, complex*16,
    dimension( 0: * ) ARF, complex*16, dimension( 0: lda-1, 0: * ) A,
    integer LDA, integer INFO)

ZTFTTR copies a triangular matrix from the rectangular full packed format (TF) to the standard full format (TR). main character energy fr fr 👑✨

Purpose 💖

ZTFTTR copies a triangular matrix A from rectangular full packed format (TF) to standard full format (TR).

Parameters 🎀

TRANSR — TRANSR is CHARACTER*1:
- = 'N': ARF is in Normal format;
- = 'C': ARF is in Conjugate-transpose format;
UPLO — UPLO is CHARACTER*1:
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
N — N is INTEGER. The order of the matrix A. N >= 0.
ARF — ARF is COMPLEX*16 array, dimension ( N*(N+1)/2 ). On entry, the upper or lower triangular matrix A stored in RFP format. For a further discussion see Notes below. 👀
A — A is COMPLEX*16 array, dimension ( LDA, N ). On exit, the triangular matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading N-by-N lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced.
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
INFO — INFO is INTEGER:
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value 💀

Author 👑

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

Further Details 🌈

We first consider Standard Packed Format when N is even. We give an example where N = 6.

    AP is Upper             AP is Lower

 00 01 02 03 04 05       00
    11 12 13 14 15       10 11
       22 23 24 25       20 21 22
          33 34 35       30 31 32 33
             44 45       40 41 42 43 44
                55       50 51 52 53 54 55

Okay bestie, so when TRANSR = 'N', RFP holds AP like this: for UPLO = 'U' the upper trapezoid A(0:5,0:2) is literally the last three columns of AP upper. And the lower triangle A(4:6,0:2)? That's the conjugate-transpose of the first three columns of AP upper. For UPLO = 'L', the lower trapezoid A(1:6,0:2) is the first three columns of AP lower, and the upper triangle A(0:2,0:2) is the conjugate-transpose of the last three columns of AP lower. To show conjugate we put -- above the element. This is the case when N is even and TRANSR = 'N'. 💅

                    RFP A                   RFP A

                                           -- -- --
                   03 04 05                33 43 53
                                              -- --
                   13 14 15                00 44 54
                                                 --
                   23 24 25                10 11 55

                   33 34 35                20 21 22
                   --
                   00 44 45                30 31 32
                   -- --
                   01 11 55                40 41 42
                   -- -- --
                   02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. So you get: ✨

                      RFP A                   RFP A

                -- -- -- --                -- -- -- -- -- --
                03 13 23 33 00 01 02    33 00 10 20 30 40 50
                -- -- -- -- --                -- -- -- -- --
                04 14 24 34 44 11 12    43 44 11 21 31 41 51
                -- -- -- -- -- --                -- -- -- --
                05 15 25 35 45 55 22    53 54 55 22 32 42 52

We next consider Standard Packed Format when N is odd. We give an example where N = 5.

                AP is Upper                 AP is Lower

              00 01 02 03 04              00
                 11 12 13 14              10 11
                    22 23 24              20 21 22
                       33 34              30 31 32 33
                          44              40 41 42 43 44

Let TRANSR = 'N'. RFP holds AP as follows: For UPLO = 'U' the upper trapezoid A(0:4,0:2) consists of the last three columns of AP upper. The lower triangle A(3:4,0:1) consists of conjugate-transpose of the first two columns of AP upper. For UPLO = 'L' the lower trapezoid A(0:4,0:2) consists of the first three columns of AP lower. The upper triangle A(0:1,1:2) consists of conjugate-transpose of the last two columns of AP lower. To denote conjugate we place -- above the element. This covers the case N odd and TRANSR = 'N'. 🦋

                    RFP A                   RFP A

                                              -- --
                   02 03 04                00 33 43
                                                 --
                   12 13 14                10 11 44

                   22 23 24                20 21 22
                   --
                   00 33 34                30 31 32
                   -- --
                   01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets: 💖

                      RFP A                   RFP A

                -- -- --                   -- -- -- -- -- --
                02 12 22 00 01             00 10 20 30 40 50
                -- -- -- --                   -- -- -- -- --
                03 13 23 33 11             33 11 21 31 41 51
                -- -- -- -- --                   -- -- -- --
                04 14 24 34 44             43 44 22 32 42 52

`ZTGSEN` 🌟

   subroutine ztgsen (integer IJOB, logical WANTQ, logical WANTZ, logical,
       dimension( * ) SELECT, integer N, complex*16, dimension( lda, * ) A,
       integer LDA, complex*16, dimension( ldb, * ) B, integer LDB, complex*16,
       dimension( * ) ALPHA, complex*16, dimension( * ) BETA, complex*16,
       dimension( ldq, * ) Q, integer LDQ, complex*16, dimension( ldz, * ) Z,
       integer LDZ, integer M, double precision PL, double precision PR, double
       precision, dimension( * ) DIF, complex*16, dimension( * ) WORK, integer
       LWORK, integer, dimension( * ) IWORK, integer LIWORK, integer INFO)
       ZTGSEN

Purpose

Okay so ZTGSEN reorders the generalized Schur decomposition of a complex matrix pair (A, B) (like, using a unitary equivalence transformation Q**H * (A, B) * Z), so that a selected cluster of eigenvalues ends up in the leading diagonal blocks of the pair (A,B). The leading columns of Q and Z form unitary bases of the corresponding left and right eigenspaces (deflating subspaces). And (A, B) must be in generalized Schur canonical form, which means A and B are both upper triangular. 🔥

Also, ZTGSEN computes the generalized eigenvalues

w(j)= ALPHA(j) / BETA(j)

of the reordered matrix pair (A, B). 💅

Optionally, this routine computes estimates of reciprocal condition numbers for eigenvalues and eigenspaces. These are Difu[(A11,B11), (A22,B22)] and Difl[(A11,B11), (A22,B22)], i.e. the separation(s) between the matrix pairs (A11, B11) and (A22,B22) that correspond to the selected cluster and the eigenvalues outside the cluster, respectively, and norms of 'projections' onto left and right eigenspaces with respect to the selected cluster in the (1,1)-block. ✨

Parameters

IJOB — IJOB is INTEGER. Specifies whether condition numbers are required for the cluster of eigenvalues (PL and PR) or the deflating subspaces (Difu and Difl):
- =0: Only reorder w.r.t. SELECT. No extras.
- =1: Reciprocal of norms of 'projections' onto left and right eigenspaces w.r.t. the selected cluster (PL and PR).
- =2: Upper bounds on Difu and Difl. F-norm-based estimate (DIF(1:2)).
- =3: Estimate of Difu and Difl. 1-norm-based estimate (DIF(1:2)). About 5 times as expensive as IJOB = 2.
- =4: Compute PL, PR and DIF (i.e. 0, 1 and 2 above): Economic version to get it all.
- =5: Compute PL, PR and DIF (i.e. 0, 1 and 3 above)

bestie, pick your fighter 💅

WANTQ — WANTQ is LOGICAL. .TRUE. : update the left transformation matrix Q; .FALSE.: do not update Q.
WANTZ — WANTZ is LOGICAL. .TRUE. : update the right transformation matrix Z; .FALSE.: do not update Z.
SELECT — SELECT is LOGICAL array, dimension (N). SELECT specifies the eigenvalues in the selected cluster. To select an eigenvalue w(j), SELECT(j) must be set to .TRUE..
N — N is INTEGER. The order of the matrices A and B. N >= 0.
A — A is COMPLEX*16 array, dimension(LDA,N). On entry, the upper triangular matrix A, in generalized Schur canonical form. On exit, A is overwritten by the reordered matrix A.
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
B — B is COMPLEX*16 array, dimension(LDB,N). On entry, the upper triangular matrix B, in generalized Schur canonical form. On exit, B is overwritten by the reordered matrix B.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
ALPHA — ALPHA is COMPLEX*16 array, dimension (N).
BETA — BETA is COMPLEX*16 array, dimension (N). The diagonal elements of A and B, respectively, when the pair (A,B) has been reduced to generalized Schur form. ALPHA(i)/BETA(i) i=1,...,N are the generalized eigenvalues.
Q — Q is COMPLEX*16 array, dimension (LDQ,N). On entry, if WANTQ = .TRUE., Q is an N-by-N matrix. On exit, Q has been postmultiplied by the left unitary transformation matrix which reorder (A, B); The leading M columns of Q form orthonormal bases for the specified pair of left eigenspaces (deflating subspaces). If WANTQ = .FALSE., Q is not referenced.
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= 1. If WANTQ = .TRUE., LDQ >= N.
Z — Z is COMPLEX*16 array, dimension (LDZ,N). On entry, if WANTZ = .TRUE., Z is an N-by-N matrix. On exit, Z has been postmultiplied by the left unitary transformation matrix which reorder (A, B); The leading M columns of Z form orthonormal bases for the specified pair of left eigenspaces (deflating subspaces). If WANTZ = .FALSE., Z is not referenced.
LDZ — LDZ is INTEGER. The leading dimension of the array Z. LDZ >= 1. If WANTZ = .TRUE., LDZ >= N.
M — M is INTEGER. The dimension of the specified pair of left and right eigenspaces, (deflating subspaces) 0 <= M <= N.
PL — PL is DOUBLE PRECISION.
PR — PR is DOUBLE PRECISION. If IJOB = 1, 4 or 5, PL, PR are lower bounds on the reciprocal of the norm of 'projections' onto left and right eigenspace with respect to the selected cluster. 0 < PL, PR <= 1. If M = 0 or M = N, PL = PR = 1. If IJOB = 0, 2 or 3 PL, PR are not referenced.
DIF — DIF is DOUBLE PRECISION array, dimension (2). If IJOB >= 2, DIF(1:2) store the estimates of Difu and Difl. If IJOB = 2 or 4, DIF(1:2) are F-norm-based upper bounds on Difu and Difl. If IJOB = 3 or 5, DIF(1:2) are 1-norm-based estimates of Difu and Difl, computed using reversed communication with ZLACN2. If M = 0 or N, DIF(1:2) = F-norm([A, B]). If IJOB = 0 or 1, DIF is not referenced.
WORK — WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= 1. If IJOB = 1, 2 or 4, LWORK >= 2*M*(N-M). If IJOB = 3 or 5, LWORK >= 4*M*(N-M).

And if LWORK = -1? Then a workspace query is assumed, bestie — the routine only calculates the optimal size of the WORK array, hands that value back as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. So XERBLA stays quiet, no cap. 🤫

IWORK — IWORK is INTEGER array, dimension (MAX(1,LIWORK)). On exit, if INFO = 0, IWORK(1) returns the optimal LIWORK. 💖
LIWORK — LIWORK is INTEGER, and it's the dimension of the array IWORK. LIWORK >= 1.
- If IJOB = 1, 2 or 4, then LIWORK >= N+2;
- If IJOB = 3 or 5, then LIWORK >= MAX(N+2, 2*M*(N-M)).

And if LIWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the IWORK array, returns this value as the first entry of the IWORK array, and no error message related to LIWORK is issued by XERBLA. ✨

INFO — INFO is INTEGER
- =0: Successful exit. 🎉
- <0: If INFO = -i, the i-th argument had an illegal value. 🙈
- =1: Reordering of (A, B) failed because the transformed matrix pair (A, B) would be too far from generalized Schur form; the problem is very ill-conditioned. (A, B) may have been partially reordered. If requested, 0 is returned in DIF(*), PL and PR. 💀

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🧚 Further Details:

ZTGSEN first collects the selected eigenvalues by computing unitary U and W that move them to the top left corner of (A, B). In other words, the selected eigenvalues are the eigenvalues of (A11, B11) in

            U**H*(A, B)*W = (A11 A12) (B11 B12) n1
                            ( 0  A22),( 0  B22) n2
                              n1  n2    n1  n2

where N = n1+n2 and U**H means the conjugate transpose of U. The first n1 columns of U and W span the specified pair of left and right eigenspaces (deflating subspaces) of (A, B). 🦋

If (A, B) has been obtained from the generalized real Schur decomposition of a matrix pair (C, D) = Q*(A, B)*Z**H, then the reordered generalized Schur form of (C, D) is given by

         (C, D) = (Q*U)*(U**H *(A, B)*W)*(Z*W)**H,

and the first n1 columns of Q*U and Z*W span the corresponding deflating subspaces of (C, D) (Q and Z store Q*U and Z*W, resp.). 💅

Note that if the selected eigenvalue is sufficiently ill-conditioned, then its value may differ significantly from its value before reordering. Yes, seriously — it can move on you. 😭

The reciprocal condition numbers of the left and right eigenspaces spanned by the first n1 columns of U and W (or Q*U and Z*W) may be returned in DIF(1:2), corresponding to Difu and Difl, resp. ✨

The Difu and Difl are defined as:

     Difu[(A11, B11), (A22, B22)] = sigma-min( Zu )
and
     Difl[(A11, B11), (A22, B22)] = Difu[(A22, B22), (A11, B11)],

where sigma-min(Zu) is the smallest singular value of the (2*n1*n2)-by-(2*n1*n2) matrix

     Zu = [ kron(In2, A11)  -kron(A22**H, In1) ]
          [ kron(In2, B11)  -kron(B22**H, In1) ].

Here, Inx is the identity matrix of size nx and A22**H is the conjugate transpose of A22. kron(X, Y) is the Kronecker product between the matrices X and Y. 🧮

When DIF(2) is small, small changes in (A, B) can cause large changes in the deflating subspace. An approximate (asymptotic) bound on the maximum angular error in the computed deflating subspaces is

     EPS * norm((A, B)) / DIF(2),

where EPS is the machine precision. 👑

The reciprocal norm of the projectors on the left and right eigenspaces associated with (A11, B11) may be returned in PL and PR. They are computed as follows. First we compute L and R so that P*(A, B)*Q is block diagonal, where

     P = ( I -L ) n1           Q = ( I R ) n1
         ( 0  I ) n2    and        ( 0 I ) n2
           n1 n2                    n1 n2

and (L, R) is the solution to the generalized Sylvester equation

     A11*R - L*A22 = -A12
     B11*R - L*B22 = -B12

Then PL = (F-norm(L)**2+1)**(-1/2) and PR = (F-norm(R)**2+1)**(-1/2). An approximate (asymptotic) bound on the average absolute error of the selected eigenvalues is

     EPS * norm((A, B)) / PL.

There are also global error bounds which valid for perturbations up to a certain restriction: A lower bound (x) on the smallest F-norm(E,F) for which an eigenvalue of (A11, B11) may move and coalesce with an eigenvalue of (A22, B22) under perturbation (E,F), (i.e. (A + E, B + F), is

     x = min(Difu,Difl)/((1/(PL*PL)+1/(PR*PR))**(1/2)+2*max(1/PL,1/PR)).

An approximate bound on x can be computed from DIF(1:2), PL and PR. 🌸

If y = ( F-norm(E,F) / x) <= 1, the angles between the perturbed (L', R') and unperturbed (L, R) left and right deflating subspaces associated with the selected cluster in the (1,1)-blocks can be bounded as

     max-angle(L, L') <= arctan( y * PL / (1 - y * (1 - PL * PL)**(1/2))
     max-angle(R, R') <= arctan( y * PR / (1 - y * (1 - PR * PR)**(1/2))

See LAPACK User's Guide section 4.11 or the following references for more information. 📚

Note that if the default method for computing the Frobenius-norm-based estimate DIF is not wanted (see ZLATDF), then the parameter IDIFJB (see below) should be changed from 3 to 4 (routine ZLATDF (IJOB = 2 will be used)). See ZTGSYL for more details. iykyk 💅

🫶 Contributors:

Bo Kagstrom and Peter Poromaa, Department of Computing Science, Umea University, S-901 87 Umea, Sweden.

🌈 References:

[1] B. Kagstrom; A Direct Method for Reordering Eigenvalues in the Generalized Real Schur Form of a Regular Matrix Pair (A, B), in M.S. Moonen et al (eds), Linear Algebra for Large Scale and Real-Time Applications, Kluwer Academic Publ. 1993, pp 195-218.

[2] B. Kagstrom and P. Poromaa; Computing Eigenspaces with Specified Eigenvalues of a Regular Matrix Pair (A, B) and Condition Estimation: Theory, Algorithms and Software, Report UMINF - 94.04, Department of Computing Science, Umea University, S-901 87 Umea, Sweden, 1994. Also as LAPACK Working Note 87. To appear in Numerical Algorithms, 1996.

[3] B. Kagstrom and P. Poromaa, LAPACK-Style Algorithms and Software for Solving the Generalized Sylvester Equation and Estimating the Separation between Regular Matrix Pairs, Report UMINF - 93.23, Department of Computing Science, Umea University, S-901 87 Umea, Sweden, December 1993, Revised April 1994, Also as LAPACK working Note 75. To appear in ACM Trans. on Math. Software, Vol 22, No 1, 1996.

🔥 subroutine `ztgsja`

subroutine ztgsja (character JOBU, character JOBV, character JOBQ, integer
    M, integer P, integer N, integer K, integer L, complex*16, dimension(
    lda, * ) A, integer LDA, complex*16, dimension( ldb, * ) B, integer LDB,
    double precision TOLA, double precision TOLB, double precision,
    dimension( * ) ALPHA, double precision, dimension( * ) BETA, complex*16,
    dimension( ldu, * ) U, integer LDU, complex*16, dimension( ldv, * ) V,
    integer LDV, complex*16, dimension( ldq, * ) Q, integer LDQ, complex*16,
    dimension( * ) WORK, integer NCYCLE, integer INFO)

ZTGSJA 👑

🎯 Purpose:

ZTGSJA computes the generalized singular value decomposition (GSVD) of two complex upper triangular (or trapezoidal) matrices A and B. iconic ✨

On entry, it is assumed that matrices A and B have the following forms, which may be obtained by the preprocessing subroutine ZGGSVP from a general M-by-N matrix A and P-by-N matrix B:

             N-K-L  K    L
   A =    K ( 0    A12  A13 ) if M-K-L >= 0;
          L ( 0     0   A23 )
      M-K-L ( 0     0    0  )

           N-K-L  K    L
   A =  K ( 0    A12  A13 ) if M-K-L < 0;
      M-K ( 0     0   A23 )

           N-K-L  K    L
   B =  L ( 0     0   B13 )
      P-L ( 0     0    0  )

where the K-by-K matrix A12 and L-by-L matrix B13 are nonsingular upper triangular; A23 is L-by-L upper triangular if M-K-L >= 0, otherwise A23 is (M-K)-by-L upper trapezoidal. 🧚

On exit,

       U**H *A*Q = D1*( 0 R ),    V**H *B*Q = D2*( 0 R ),

where U, V and Q are unitary matrices. R is a nonsingular upper triangular matrix, and D1 and D2 are ``diagonal'' matrices, which are of the following structures:

If M-K-L >= 0,

                    K  L
       D1 =     K ( I  0 )
                L ( 0  C )
            M-K-L ( 0  0 )

                   K  L
       D2 = L   ( 0  S )
            P-L ( 0  0 )

               N-K-L  K    L
  ( 0 R ) = K (  0   R11  R12 ) K
            L (  0    0   R22 ) L

where

  C = diag( ALPHA(K+1), ... , ALPHA(K+L) ),
  S = diag( BETA(K+1),  ... , BETA(K+L) ),
  C**2 + S**2 = I.

  R is stored in A(1:K+L,N-K-L+1:N) on exit.

If M-K-L < 0,

               K M-K K+L-M
    D1 =   K ( I  0    0   )
         M-K ( 0  C    0   )

                 K M-K K+L-M
    D2 =   M-K ( 0  S    0   )
         K+L-M ( 0  0    I   )
           P-L ( 0  0    0   )

               N-K-L  K   M-K  K+L-M
( 0 R ) =    K ( 0    R11  R12  R13  )
          M-K ( 0     0   R22  R23  )
        K+L-M ( 0     0    0   R33  )

where C = diag( ALPHA(K+1), ... , ALPHA(M) ), S = diag( BETA(K+1), ... , BETA(M) ), C**2 + S**2 = I.

R = ( R11 R12 R13 ) is stored in A(1:M, N-K-L+1:N) and R33 is stored
    (  0  R22 R23 )
in B(M-K+1:L,N+M-K-L+1:N) on exit.

The computation of the unitary transformation matrices U, V or Q is optional. These matrices may either be formed explicitly, or they may be postmultiplied into input matrices U1, V1, or Q1. 🦋

🎀 Parameters

JOBU — JOBU is CHARACTER*1
- = 'U': U must contain a unitary matrix U1 on entry, and the product U1*U is returned;
- = 'I': U is initialized to the unit matrix, and the unitary matrix U is returned;
- = 'N': U is not computed.
JOBV —
JOBV — CHARACTER*1, okay so here's the deal:
- 'V': V has to walk in already holding a unitary matrix V1, and you get handed back the product V1*V;
- 'I': V gets initialized to the unit matrix, and boom, you get the unitary matrix V returned;
- 'N': V is not computed. not even a little bit. 💀
JOBQ — CHARACTER*1, same energy as JOBV but for Q:
- 'Q': Q must already contain a unitary matrix Q1 on entry, and the product Q1*Q is returned;
- 'I': Q is initialized to the unit matrix, and the unitary matrix Q is returned;
- 'N': Q is not computed.
M — M is INTEGER. The number of rows of the matrix A. M >= 0.
P — P is INTEGER. The number of rows of the matrix B. P >= 0.
N — N is INTEGER. The number of columns of the matrices A and B. N >= 0.
K — K is INTEGER.
L — L is INTEGER.

K and L are the ones that pin down the subblocks inside the input matrices A and B: A23 = A(K+1:MIN(K+L,M),N-L+1:N) and B13 = B(1:L,,N-L+1:N) of A and B, whose GSVD is about to be computed by ZTGSJA. Peep Further Details for the whole lore. ✨

A — A is COMPLEX*16 array, dimension (LDA,N). On entry, the M-by-N matrix A. On exit, A(N-K+1:N,1:MIN(K+L,M) ) contains the triangular matrix R or part of R. See Purpose for details, bestie. 👑
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M).
B — B is COMPLEX*16 array, dimension (LDB,N). On entry, the P-by-N matrix B. On exit, if necessary, B(M-K+1:L,N+M-K-L+1:N) contains a part of R. See Purpose for details.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,P).
TOLA — TOLA is DOUBLE PRECISION.
TOLB — TOLB is DOUBLE PRECISION.

TOLA and TOLB are the convergence criteria for the Jacobi-Kogbetliantz iteration procedure. Generally they're the same as the ones used in the preprocessing step, like, say:

TOLA = MAX(M,N)*norm(A)*MAZHEPS,
TOLB = MAX(P,N)*norm(B)*MAZHEPS.

ALPHA — ALPHA is DOUBLE PRECISION array, dimension (N).
BETA — BETA is DOUBLE PRECISION array, dimension (N).

On exit, ALPHA and BETA are holding the generalized singular value pairs of A and B, and it's giving:

ALPHA(1:K) = 1,
BETA(1:K)  = 0,

and if M-K-L >= 0,

ALPHA(K+1:K+L) = diag(C),
BETA(K+1:K+L)  = diag(S),

or if M-K-L < 0,

ALPHA(K+1:M)= C, ALPHA(M+1:K+L)= 0
BETA(K+1:M) = S, BETA(M+1:K+L) = 1.

Furthermore, if K+L < N,

ALPHA(K+L+1:N) = 0 and
BETA(K+L+1:N)  = 0.

U — U is COMPLEX*16 array, dimension (LDU,M). On entry, if JOBU = 'U', U must contain a matrix U1 (usually the unitary matrix returned by ZGGSVP). On exit:
- if JOBU = 'I', U contains the unitary matrix U;
- if JOBU = 'U', U contains the product U1*U.

If JOBU = 'N', U is not referenced. leave her alone. 🙈

LDU — LDU is INTEGER. The leading dimension of the array U. LDU >= max(1,M) if JOBU = 'U'; LDU >= 1 otherwise.
V — V is COMPLEX*16 array, dimension (LDV,P). On entry, if JOBV = 'V', V must contain a matrix V1 (usually the unitary matrix returned by ZGGSVP). On exit:
- if JOBV = 'I', V contains the unitary matrix V;
- if JOBV = 'V', V contains the product V1*V.

If JOBV = 'N', V is not referenced.

LDV — LDV is INTEGER. The leading dimension of the array V. LDV >= max(1,P) if JOBV = 'V'; LDV >= 1 otherwise.
Q — Q is COMPLEX*16 array, dimension (LDQ,N). On entry, if JOBQ = 'Q', Q must contain a matrix Q1 (usually the unitary matrix returned by ZGGSVP). On exit:
- if JOBQ = 'I', Q contains the unitary matrix Q;
- if JOBQ = 'Q', Q contains the product Q1*Q.

If JOBQ = 'N', Q is not referenced.

LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= max(1,N) if JOBQ = 'Q'; LDQ >= 1 otherwise.
WORK — WORK is COMPLEX*16 array, dimension (2*N).
NCYCLE — NCYCLE is INTEGER. The number of cycles required for convergence. slay, she converged. 💅
INFO — INFO is INTEGER:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. not cute.
- = 1: the procedure does not converge after MAXIT cycles. it's giving stubborn. 😭

🔧 Internal Parameters 🔧

MAXIT — INTEGER. MAXIT specifies the total loops that the iterative procedure may take. If after MAXIT cycles the routine fails to converge, we return INFO = 1.

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌈 Further Details 🌈

ZTGSJA essentially uses a variant of Kogbetliantz algorithm to reduce min(L,M-K)-by-L triangular (or trapezoidal) matrix A23 and L-by-L matrix B13 to the form:

U1**H *A13*Q1 = C1*R1; V1**H *B13*Q1 = S1*R1,

where U1, V1 and Q1 are unitary matrix. C1 and S1 are diagonal matrices satisfying

C1**2 + S1**2 = I,

and R1 is an L-by-L nonsingular upper triangular matrix. periodt. 💜

subroutine ztgsna (character JOB, character HOWMNY, logical, dimension( * )
    SELECT, integer N, complex*16, dimension( lda, * ) A, integer LDA,
    complex*16, dimension( ldb, * ) B, integer LDB, complex*16, dimension(
    ldvl, * ) VL, integer LDVL, complex*16, dimension( ldvr, * ) VR, integer
    LDVR, double precision, dimension( * ) S, double precision, dimension( *
    ) DIF, integer MM, integer M, complex*16, dimension( * ) WORK, integer
    LWORK, integer, dimension( * ) IWORK, integer INFO)

✨ ZTGSNA ✨

💖 Purpose 💖

ZTGSNA estimates reciprocal condition numbers for specified eigenvalues and/or eigenvectors of a matrix pair (A, B).

(A, B) must be in generalized Schur canonical form, that is, A and B are both upper triangular. no exceptions, bestie.

🎀 Parameters 🎀

JOB — JOB is CHARACTER*1. Specifies whether condition numbers are required for eigenvalues (S) or eigenvectors (DIF):
- 'E': for eigenvalues only (S);
- 'V': for eigenvectors only (DIF);
- 'B': for both eigenvalues and eigenvectors (S and DIF). both. because why not. 🫶
HOWMNY — HOWMNY is CHARACTER*1:
- 'A': compute condition numbers for all eigenpairs;
- 'S': compute condition numbers for selected eigenpairs specified by the array SELECT.
SELECT — SELECT is LOGICAL array, dimension (N). If HOWMNY = 'S', SELECT specifies the eigenpairs for which condition numbers are required. To select condition numbers for the corresponding j-th eigenvalue and/or eigenvector, SELECT(j) must be set to .TRUE.. If HOWMNY = 'A', SELECT is not referenced.
N — N is INTEGER. The order of the square matrix pair (A, B). N >= 0.
A — A is COMPLEX*16 array, dimension (LDA,N). The upper triangular matrix A in the pair (A,B).
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
B — B is COMPLEX*16 array, dimension (LDB,N). The upper triangular matrix B in the pair (A, B).
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
VL — VL is COMPLEX*16 array, dimension (LDVL,M). IF JOB = 'E' or 'B', VL must contain left eigenvectors of (A, B), corresponding to the eigenpairs specified by HOWMNY and SELECT. The eigenvectors must be stored in consecutive columns of VL, as returned by ZTGEVC. If JOB = 'V', VL is not referenced.
LDVL — LDVL is INTEGER. The leading dimension of the array VL. LDVL >= 1; and If JOB = 'E' or 'B', LDVL >= N.
VR — VR is COMPLEX*16 array, dimension (LDVR,M). IF JOB = 'E' or 'B', VR must contain right eigenvectors of (A, B), corresponding to the eigenpairs specified by HOWMNY and SELECT. The eigenvectors must be stored in consecutive columns of VR, as returned by ZTGEVC. If JOB = 'V', VR is not referenced.
LDVR — LDVR is INTEGER. The leading dimension of the array VR. LDVR >= 1; If JOB = 'E' or 'B', LDVR >= N.
S — S is DOUBLE PRECISION array, dimension (MM). If JOB = 'E' or 'B', the reciprocal condition numbers of the selected eigenvalues, stored in consecutive elements of the array. If JOB = 'V', S is not referenced.
DIF — DIF is DOUBLE PRECISION array, dimension (MM). If JOB = 'V' or 'B', the estimated reciprocal condition numbers of the selected eigenvectors, stored in consecutive elements of the array.

If the eigenvalues cannot be reordered to compute DIF(j), DIF(j) is set to 0; this can only occur when the true value would be very small anyway.

For each eigenvalue/vector specified by SELECT, DIF stores a Frobenius norm-based estimate of Difl. If JOB = 'E', DIF is not referenced.

MM — MM is INTEGER. The number of elements in the arrays S and DIF. MM >= M.
M —
M is INTEGER — the number of elements in the arrays S and DIF that get used to store the condition numbers we're talking about; you use one element per selected eigenvalue, bestie. And if HOWMNY = 'A', then M gets set to N. Slay. 💅
WORK is a COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, then WORK(1) comes back holding the optimal LWORK. Iconic little sneak peek. ✨
LWORK is INTEGER — it's the dimension of the WORK array. So LWORK >= max(1,N). And heads up, if JOB = 'V' or 'B', then LWORK >= max(1,2*N*N). Not me warning you about this twice, but like, fr fr, size it right. 🫶
IWORK is an INTEGER array, dimension (N+2). And if JOB = 'E', IWORK is literally not referenced at all — it's giving "you're off the clock." 💀
INFO is INTEGER:
- = 0: Successful exit 🎉
- < 0: If INFO = -i, the i-th argument had an illegal value 😭

👑 Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🌈 Further Details:

Okay so the reciprocal of the condition number of the i-th generalized eigenvalue w = (a, b) is defined as

S(I) = (|v**HAu|**2 + |v**HBu|**2)**(1/2) / (norm(u)*norm(v))

where u and v are the right and left eigenvectors of (A, B) corresponding to w; |z| denotes the absolute value of the complex number, and norm(u) denotes the 2-norm of the vector u. The pair (a, b) corresponds to an eigenvalue w = a/b (= v**HAu/v**HBu) of the matrix pair (A, B). And if both a and b equal zero, then (A,B) is singular and S(I) = -1 is returned. That's the vibe check result, no cap. 🦋

An approximate error bound on the chordal distance between the i-th computed generalized eigenvalue w and the corresponding exact eigenvalue lambda is

chord(w, lambda) <=   EPS * norm(A, B) / S(I),

where EPS is the machine precision. Bestie, EPS is always lurking. 👀

The reciprocal of the condition number of the right eigenvector u and left eigenvector v corresponding to the generalized eigenvalue w is defined as follows. Suppose

         (A, B) = ( a   *  ) ( b  *  )  1
                  ( 0  A22 ),( 0 B22 )  n-1
                    1  n-1     1 n-1

Then the reciprocal condition number DIF(I) is

Difl[(a, b), (A22, B22)]  = sigma-min( Zl )

where sigma-min(Zl) denotes the smallest singular value of

Zl = [ kron(a, In-1) -kron(1, A22) ]
     [ kron(b, In-1) -kron(1, B22) ].

Here In-1 is the identity matrix of size n-1 and X**H is the conjugate transpose of X. kron(X, Y) is the Kronecker product between the matrices X and Y. Kronecker product is so main character energy, honestly. 💜

We approximate the smallest singular value of Zl with an upper bound. This is done by ZLATDF. Shoutout to ZLATDF for doing the actual work. 🎀

An approximate error bound for a computed eigenvector VL(i) or VR(i) is given by

EPS * norm(A, B) / DIF(i).

See ref. [2-3] for more details and further references. Go read them, bestie, they're iconic. 📚

💖 Contributors:

Bo Kagstrom and Peter Poromaa, Department of Computing Science, Umea University, S-901 87 Umea, Sweden.

🌸 References:

B. Kagstrom; A Direct Method for Reordering Eigenvalues in the Generalized Real Schur Form of a Regular Matrix Pair (A, B), in M.S. Moonen et al (eds), Linear Algebra for Large Scale and Real-Time Applications, Kluwer Academic Publ. 1993, pp 195-218.
B. Kagstrom and P. Poromaa; Computing Eigenspaces with Specified Eigenvalues of a Regular Matrix Pair (A, B) and Condition Estimation: Theory, Algorithms and Software, Report UMINF - 94.04, Department of Computing Science, Umea University, S-901 87 Umea, Sweden, 1994. Also as LAPACK Working Note 87. To appear in Numerical Algorithms, 1996.
B. Kagstrom and P. Poromaa, LAPACK-Style Algorithms and Software for Solving the Generalized Sylvester Equation and Estimating the Separation between Regular Matrix Pairs, Report UMINF - 93.23, Department of Computing Science, Umea University, S-901 87 Umea, Sweden, December 1993, Revised April 1994, Also as LAPACK Working Note 75. To appear in ACM Trans. on Math. Software, Vol 22, No 1, 1996.

✨ subroutine ztpcon

subroutine ztpcon (character NORM, character UPLO, character DIAG, integer
    N, complex*16, dimension( * ) AP, double precision RCOND, complex*16,
    dimension( * ) WORK, double precision, dimension( * ) RWORK, integer
    INFO)

ZTPCON — okay so this one is a whole moment. ✨

🎯 Purpose:

ZTPCON estimates the reciprocal of the condition number of a packed triangular matrix A, in either the 1-norm or the infinity-norm. Both, you say? You pick, bestie. 💅

The norm of A is computed and an estimate is obtained for norm(inv(A)), then the reciprocal of the condition number is computed as

RCOND = 1 / ( norm(A) * norm(inv(A)) ).

The way that formula just works. Math ate. 🔥

🌟 Parameters

NORM is CHARACTER*1 — it specifies whether the 1-norm condition number or the infinity-norm condition number is required:
- = '1' or 'O': 1-norm;
- = 'I': Infinity-norm.
UPLO is CHARACTER*1:
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
DIAG is CHARACTER*1:
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N is INTEGER — the order of the matrix A. N >= 0.
AP is a COMPLEX*16 array, dimension (N*(N+1)/2) — the upper or lower triangular matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
- if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.

And if DIAG = 'U', the diagonal elements of A are not referenced and are assumed to be 1. Not me just assuming they're 1, but like, that's the deal. 🙈

RCOND is DOUBLE PRECISION — the reciprocal of the condition number of the matrix A, computed as RCOND = 1/(norm(A) * norm(inv(A))).
WORK is a COMPLEX*16 array, dimension (2*N).
RWORK is a DOUBLE PRECISION array, dimension (N).
INFO is INTEGER:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 😭

👑 Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🦋 subroutine ztpmqrt

subroutine ztpmqrt (character SIDE, character TRANS, integer M, integer N,
    integer K, integer L, integer NB, complex*16, dimension( ldv, * ) V,
    integer LDV, complex*16, dimension( ldt, * ) T, integer LDT, complex*16,
    dimension( lda, * ) A, integer LDA, complex*16, dimension( ldb, * ) B,
    integer LDB, complex*16, dimension( * ) WORK, integer INFO)

ZTPMQRT — the name is giving "I'm a QR factorization but make it triangular-pentagonal." 🌈

🎯 Purpose:

ZTPMQRT applies a complex orthogonal matrix Q obtained from a 'triangular-pentagonal' complex block reflector H to a general complex matrix C, which consists of two blocks A and B. Two blocks, one vibe. 🫶

🌟 Parameters

SIDE is CHARACTER*1:
- = 'L': apply Q or Q**H from the Left;
- = 'R': apply Q or Q**H from the Right.
TRANS is CHARACTER*1:
- = 'N': No transpose, apply Q;
- = 'C': Conjugate transpose, apply Q**H.
M is INTEGER — the number of rows of the matrix B. M >= 0.
N is INTEGER — the number of columns of the matrix B. N >= 0.
K is INTEGER — the number of elementary reflectors whose product defines the matrix Q.
L is INTEGER — the order of the trapezoidal part of V. K >= L >= 0. See Further Details. 👀
NB is INTEGER — the block size used for the storage of T. K >= NB >= 1. This must be the same value of NB used to generate T in CTPQRT. Like, it has to match, bestie, don't play. 💅
V is a COMPLEX*16 array, dimension (LDV,K) — the i-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CTPQRT in B. See Further Details.
LDV is INTEGER — the leading dimension of the array V. If SIDE = 'L', LDV >= max(1,M); if SIDE = 'R', LDV >= max(1,N).
T is a COMPLEX*16 array, dimension (LDT,K) — the upper triangular factors of the block reflectors as returned by CTPQRT, stored as a NB-by-K matrix.
LDT is INTEGER — the leading dimension of the array T. LDT >= NB.
A is a COMPLEX*16 array, dimension
- (LDA,N) if SIDE = 'L' or
- (LDA,K) if SIDE = 'R'

On entry, the K-by-N or M-by-K matrix A. On exit, A is overwritten by the corresponding block of Q*C or Q**H*C or C*Q or C*Q**H. See Further Details. She gets overwritten, so say goodbye to the old her. 😭

LDA is INTEGER — the leading dimension of the array A. If SIDE = 'L', LDC >= max(1,K); If SIDE = 'R', LDC >= max(1,M).
B is a COMPLEX*16 array, dimension (LDB,N) — On entry, the M-by-N matrix B. On exit, B is overwritten by the corresponding block of Q*C or Q**H*C or C*Q or C*Q**H. See Further Details.
LDB is INTEGER — the leading dimension of the array B. LDB >= max(1,M).
WORK is a COMPLEX*16 array. The dimension of WORK is N*NB if SIDE = 'L', or M*NB if SIDE = 'R'.
INFO is INTEGER:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 😭

👑 Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🌈 Further Details:

The columns of the pentagonal matrix V contain the elementary reflectors H(1), H(2), ..., H(K); V is composed of a rectangular block V1 and a trapezoidal block V2:

V = [V1]
    [V2].

Two blocks stacked, and honestly? It's giving pentagon. 🔥

The size of the trapezoidal block V2 is lowkey decided by the parameter L, where 0 <= L <= K. V2 is upper trapezoidal, and it's literally made of the first L rows of a K-by-K upper triangular matrix. So if L=K, V2 is upper triangular 🎀 — and if L=0, there is no trapezoidal block at all, hence V = V1 is rectangular. The way that math just works.

If SIDE = 'L':  C = [A]  where A is K-by-N,  B is M-by-N and V is M-by-K.
                    [B]

If SIDE = 'R':  C = [A B]  where A is M-by-K, B is M-by-N and V is N-by-K.

The complex orthogonal matrix Q is formed from V and T. ✨

If TRANS='N' and SIDE='L', C is on exit replaced with Q * C.
If TRANS='C' and SIDE='L', C is on exit replaced with Q**H * C.
If TRANS='N' and SIDE='R', C is on exit replaced with C * Q.
If TRANS='C' and SIDE='R', C is on exit replaced with C * Q**H.

subroutine ztpqrt (integer M, integer N, integer L, integer NB, complex*16,
    dimension( lda, * ) A, integer LDA, complex*16, dimension( ldb, * ) B,
    integer LDB, complex*16, dimension( ldt, * ) T, integer LDT, complex*16,
    dimension( * ) WORK, integer INFO)

✨ ZTPQRT ✨

Purpose:

ZTPQRT computes a blocked QR factorization of a complex 'triangular-pentagonal' matrix C, which is composed of a triangular block A and pentagonal block B, using the compact WY representation for Q. Bestie, it's giving decomposition. 💅

Parameters

M — M is INTEGER. The number of rows of the matrix B. M >= 0.
N — N is INTEGER. The number of columns of the matrix B, and the order of the triangular matrix A. N >= 0.
L — L is INTEGER. The number of rows of the upper trapezoidal part of B. MIN(M,N) >= L >= 0. See Further Details.
NB — NB is INTEGER. The block size to be used in the blocked QR. N >= NB >= 1.
A — A is COMPLEX*16 array, dimension (LDA,N). On entry, the upper triangular N-by-N matrix A. On exit, the elements on and above the diagonal of the array contain the upper triangular matrix R. 🫶
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
B — B is COMPLEX*16 array, dimension (LDB,N). On entry, the pentagonal M-by-N matrix B. The first M-L rows are rectangular, and the last L rows are upper trapezoidal. On exit, B contains the pentagonal matrix V. See Further Details.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,M).
T — T is COMPLEX*16 array, dimension (LDT,N). The upper triangular block reflectors stored in compact form as a sequence of upper triangular blocks. See Further Details.
LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= NB.
WORK — WORK is COMPLEX*16 array, dimension (NB*N).
INFO — INFO is INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 😭

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details:

The input matrix C is a (N+M)-by-N matrix

             C = [ A ]
                 [ B ]

where A is an upper triangular N-by-N matrix, and B is M-by-N pentagonal matrix consisting of a (M-L)-by-N rectangular matrix B1 on top of a L-by-N upper trapezoidal matrix B2:

             B = [ B1 ]  <- (M-L)-by-N rectangular
                 [ B2 ]  <-     L-by-N upper trapezoidal.

The upper trapezoidal matrix B2 consists of the first L rows of a N-by-N upper triangular matrix, where 0 <= L <= MIN(M,N). If L=0, B is rectangular M-by-N; if M=L=N, B is upper triangular. ✨

The matrix W stores the elementary reflectors H(i) in the i-th column below the diagonal (of A) in the (N+M)-by-N input matrix C

             C = [ A ]  <- upper triangular N-by-N
                 [ B ]  <- M-by-N pentagonal

so that W can be represented as

             W = [ I ]  <- identity, N-by-N
                 [ V ]  <- M-by-N, same form as B.

Thus, all of information needed for W is contained on exit in B, which we call V above. Note that V has the same form as B; that is,

             V = [ V1 ] <- (M-L)-by-N rectangular
                 [ V2 ] <-     L-by-N upper trapezoidal.

The columns of V represent the vectors which define the H(i)'s. 👑

The number of blocks is B = ceiling(N/NB), where each block is of order NB except for the last block, which is of order IB = N - (B-1)*NB. For each of the B blocks, a upper triangular block reflector factor is computed: T1, T2, ..., TB. The NB-by-NB (and IB-by-IB for the last block) T's are stored in the NB-by-N matrix T as

             T = [T1 T2 ... TB].

subroutine ztpqrt2 (integer M, integer N, integer L, complex*16, dimension(
    lda, * ) A, integer LDA, complex*16, dimension( ldb, * ) B, integer LDB,
    complex*16, dimension( ldt, * ) T, integer LDT, integer INFO)

💜 ZTPQRT2 💜

ZTPQRT2 computes a QR factorization of a real or complex 'triangular-pentagonal' matrix, which is composed of a triangular block and a pentagonal block, using the compact WY representation for Q.

Purpose:

ZTPQRT2 computes a QR factorization of a complex 'triangular-pentagonal' matrix C, which is composed of a triangular block A and pentagonal block B, using the compact WY representation for Q. Same energy, no blocking. 🌸

Parameters

M — M is INTEGER. The total number of rows of the matrix B. M >= 0.
N — N is INTEGER. The number of columns of the matrix B, and the order of the triangular matrix A. N >= 0.
L — L is INTEGER. The number of rows of the upper trapezoidal part of B. MIN(M,N) >= L >= 0. See Further Details.
A — A is COMPLEX*16 array, dimension (LDA,N). On entry, the upper triangular N-by-N matrix A. On exit, the elements on and above the diagonal of the array contain the upper triangular matrix R.
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
B — B is COMPLEX*16 array, dimension (LDB,N). On entry, the pentagonal M-by-N matrix B. The first M-L rows are rectangular, and the last L rows are upper trapezoidal. On exit, B contains the pentagonal matrix V. See Further Details.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,M).
T — T is COMPLEX*16 array, dimension (LDT,N). The N-by-N upper triangular factor T of the block reflector. See Further Details.
LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,N)
INFO — INFO is INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details:

The input matrix C is a (N+M)-by-N matrix

             C = [ A ]
                 [ B ]

where A is an upper triangular N-by-N matrix, and B is M-by-N pentagonal matrix consisting of a (M-L)-by-N rectangular matrix B1 on top of a L-by-N upper trapezoidal matrix B2:

             B = [ B1 ]  <- (M-L)-by-N rectangular
                 [ B2 ]  <-     L-by-N upper trapezoidal.

The matrix W stores the elementary reflectors H(i) in the i-th column below the diagonal (of A) in the (N+M)-by-N input matrix C

             C = [ A ]  <- upper triangular N-by-N
                 [ B ]  <- M-by-N pentagonal

so that W can be represented as

             W = [ I ]  <- identity, N-by-N
                 [ V ]  <- M-by-N, same form as B.

Thus, all of information needed for W is contained on exit in B, which we call V above. Note that V has the same form as B; that is,

             V = [ V1 ] <- (M-L)-by-N rectangular
                 [ V2 ] <-     L-by-N upper trapezoidal.

The columns of V represent the vectors which define the H(i)'s. The (M+N)-by-(M+N) block reflector H is then given by

             H = I - W * T * W**H

where W**H is the conjugate transpose of W and T is the upper triangular factor of the block reflector. 🦋

subroutine ztprfs (character UPLO, character TRANS, character DIAG, integer
    N, integer NRHS, complex*16, dimension( * ) AP, complex*16, dimension(
    ldb, * ) B, integer LDB, complex*16, dimension( ldx, * ) X, integer LDX,
    double precision, dimension( * ) FERR, double precision, dimension( * )
    BERR, complex*16, dimension( * ) WORK, double precision, dimension( * )
    RWORK, integer INFO)

🌈 ZTPRFS 🌈

Purpose:

ZTPRFS provides error bounds and backward error estimates for the solution to a system of linear equations with a triangular packed coefficient matrix. Basically it's the vibe-check on your answer. ✅

The solution matrix X must be computed by ZTPTRS or some other means before entering this routine. ZTPRFS does not do iterative refinement because doing so cannot improve the backward error. No cap.

Parameters

UPLO — UPLO is CHARACTER*1.
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
TRANS — TRANS is CHARACTER*1. Specifies the form of the system of equations:
- = 'N': A * X = B (No transpose)
- = 'T': A**T * X = B (Transpose)
- = 'C': A**H * X = B (Conjugate transpose)
DIAG — DIAG is CHARACTER*1.
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N
N — N is INTEGER. The order of the matrix A. N >= 0. 💖
NRHS — NRHS is INTEGER. The number of right hand sides, aka the number of columns of the matrices B and X. NRHS >= 0. slay.
AP — AP is COMPLEX*16 array, dimension (N*(N+1)/2). It's the upper or lower triangular matrix A, packed columnwise in a linear array (yes bestie, packed, like a lil suitcase 🧳). The j-th column of A lives in AP like this:

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.

If DIAG = 'U', the diagonal elements of A are not referenced and are assumed to be 1. don't even look at them 💅

B — B is COMPLEX*16 array, dimension (LDB,NRHS). The right hand side matrix B. periodt.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N). no cap.
X — X is COMPLEX*16 array, dimension (LDX,NRHS). The solution matrix X. the moment we've all been waiting for ✨
LDX — LDX is INTEGER. The leading dimension of the array X. LDX >= max(1,N).
FERR — FERR is DOUBLE PRECISION array, dimension (NRHS). The estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), then FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error. it's giving "trust but verify" 🫶
BERR — BERR is DOUBLE PRECISION array, dimension (NRHS). The componentwise relative backward error of each solution vector X(j) — i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution.
WORK — WORK is COMPLEX*16 array, dimension (2*N).
RWORK — RWORK is DOUBLE PRECISION array, dimension (N).
INFO — INFO is INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value

🌸 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

👑 `subroutine ztptri (character UPLO, character DIAG, integer N, complex16, dimension( ) AP, integer INFO)`

ZTPTRI

✨ Purpose:

ZTPTRI computes the inverse of a complex upper or lower triangular matrix A stored in packed format. flip it and reverse it 🔄

🎀 Parameters

UPLO — UPLO is CHARACTER*1
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
DIAG — DIAG is CHARACTER*1
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — N is INTEGER. The order of the matrix A. N >= 0.
AP — AP is COMPLEX*16 array, dimension (N*(N+1)/2). On entry, the upper or lower triangular matrix A, stored columnwise in a linear array. The j-th column of A is stored in the array AP as follows:

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*((2*n-j)/2) = A(i,j) for j<=i<=n.

See below for further details. On exit, the (triangular) inverse of the original matrix, in the same packed storage format. iconic behaviour, honestly 💅

INFO — INFO is INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, A(i,i) is exactly zero. The triangular matrix is singular and its inverse can not be computed. 😭 no inverse for you

💜 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🦋 Further Details:

A triangular matrix A can be transferred to packed storage using one of the following program segments:

UPLO = 'U':                      UPLO = 'L':

      JC = 1                           JC = 1
      DO 2 J = 1, N                    DO 2 J = 1, N
         DO 1 I = 1, J                    DO 1 I = J, N
            AP(JC+I-1) = A(I,J)              AP(JC+I-J) = A(I,J)
    1    CONTINUE                    1    CONTINUE
         JC = JC + J                      JC = JC + N - J + 1
    2 CONTINUE                       2 CONTINUE

🌈 `subroutine ztptrs (character UPLO, character TRANS, character DIAG, integer N, integer NRHS, complex16, dimension( ) AP, complex16, dimension( ldb, ) B, integer LDB, integer INFO)`

ZTPTRS

✨ Purpose:

ZTPTRS solves a triangular system of the form

A * X = B,  A**T * X = B,  or  A**H * X = B,

where A is a triangular matrix of order N stored in packed format, and B is an N-by-NRHS matrix. A check is made to verify that A is nonsingular. bestie we verify around here 🔍

🎀 Parameters

UPLO — UPLO is CHARACTER*1
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
TRANS — TRANS is CHARACTER*1. Specifies the form of the system of equations:
- = 'N': A * X = B (No transpose)
- = 'T': A**T * X = B (Transpose)
- = 'C': A**H * X = B (Conjugate transpose)
DIAG — DIAG is CHARACTER*1
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — N is INTEGER. The order of the matrix A. N >= 0.
NRHS — NRHS is INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
AP — AP is COMPLEX*16 array, dimension (N*(N+1)/2). The upper or lower triangular matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.

B — B is COMPLEX*16 array, dimension (LDB,NRHS). On entry, the right hand side matrix B. On exit, if INFO = 0, the solution matrix X. glow up complete 🌟
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
INFO — INFO is INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, the i-th diagonal element of A is zero, indicating that the matrix is singular and the solutions X have not been computed. 💀

💜 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

⭐ `subroutine ztpttf (character TRANSR, character UPLO, integer N, complex16, dimension( 0: ) AP, complex16, dimension( 0: ) ARF, integer INFO)`

ZTPTTF copies a triangular matrix from the standard packed format (TP) to the rectangular full packed format (TF). it's giving format-shifting, main character energy 🦋

✨ Purpose:

ZTPTTF copies a triangular matrix A from standard packed format (TP) to rectangular full packed format (TF).

🎀 Parameters

TRANSR — TRANSR is CHARACTER*1
- = 'N': ARF in Normal format is wanted;
- = 'C': ARF in Conjugate-transpose format is wanted.
UPLO — UPLO is CHARACTER*1
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
N — N is INTEGER. The order of the matrix A. N >= 0.
AP — AP is COMPLEX*16 array, dimension ( N*(N+1)/2 ). On entry, the upper or lower triangular matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.

ARF — ARF is COMPLEX*16 array, dimension ( N*(N+1)/2 ). On exit, the upper or lower triangular matrix A stored in RFP format. For a further discussion see Notes below.
INFO — INFO is INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

💜 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🦋 Further Details:

We first consider Standard Packed Format when N is even. We give an example where N = 6.

    AP is Upper             AP is Lower

  00 01 02 03 04 05       00
     11 12 13 14 15       10 11
        22 23 24 25       20 21 22
           33 34 35       30 31 32 33
              44 45       40 41 42 43 44
                 55       50 51 52 53 54 55

Let TRANSR = 'N'. RFP holds AP as follows:

For UPLO = 'U' the upper trapezoid A(0:5,0:2) consists of the last three columns of AP upper. The lower triangle A(4:6,0:2) consists of conjugate-transpose of the first three columns of AP upper.
For UPLO = 'L' the lower trapezoid A(1:6,0:2) consists of the first three columns of AP lower. The upper triangle A(0:2,0:2) consists of conjugate-transpose of the last three columns of AP lower.

To denote conjugate we place -- above the element. This covers the case N even and TRANSR = 'N'.

        RFP A                   RFP A

                               -- -- --
       03 04 05                33 43 53
                                  -- --
       13 14 15                00 44 54
                                     --
       23 24 25                10 11 55

       33 34 35                20 21 22
       --
       00 44 45                30 31 32
       -- --
       01 11 55                40 41 42
       -- -- --
       02 12 22                50 51 52

Now let TRANSR = 'C'. and bestie, RFP A in both UPLO cases is literally just the conjugate-transpose of RFP A above. so you get:

                      RFP A                   RFP A

                -- -- -- --                -- -- -- -- -- --
                03 13 23 33 00 01 02    33 00 10 20 30 40 50
                -- -- -- -- --                -- -- -- -- --
                04 14 24 34 44 11 12    43 44 11 21 31 41 51
                -- -- -- -- -- --                -- -- -- --
                05 15 25 35 45 55 22    53 54 55 22 32 42 52

Next we consider Standard Packed Format when N is odd. 🦋 example time, we're using N = 5:

                AP is Upper                 AP is Lower

              00 01 02 03 04              00
                 11 12 13 14              10 11
                    22 23 24              20 21 22
                       33 34              30 31 32 33
                          44              40 41 42 43 44

Let TRANSR = 'N'. RFP holds AP like this, okurrr:

For UPLO = 'U' the upper trapezoid A(0:4,0:2) consists of the last three columns of AP upper. The lower triangle A(3:4,0:1) consists of conjugate-transpose of the first two columns of AP upper.
For UPLO = 'L' the lower trapezoid A(0:4,0:2) consists of the first three columns of AP lower. The upper triangle A(0:1,1:2) consists of conjugate-transpose of the last two columns of AP lower.

To denote conjugate we place -- above the element. This covers the case N odd and TRANSR = 'N'. ✨

                    RFP A                   RFP A

                                              -- --
                   02 03 04                00 33 43
                                                 --
                   12 13 14                10 11 44

                   22 23 24                20 21 22
                   --
                   00 33 34                30 31 32
                   -- --
                   01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- --                   -- -- -- -- -- --
                02 12 22 00 01             00 10 20 30 40 50
                -- -- -- --                   -- -- -- -- --
                03 13 23 33 11             33 11 21 31 41 51
                -- -- -- -- --                   -- -- -- --
                04 14 24 34 44             43 44 22 32 42 52

subroutine `ztpttr` (character UPLO, integer N, complex16, dimension( ) AP, complex16, dimension( lda, ) A, integer LDA, integer INFO) 🌸

ZTPTTR copies a triangular matrix from the standard packed format (TP) to the standard full format (TR). packing hack, slay.

Purpose

ZTPTTR copies a triangular matrix A from standard packed format (TP) to standard full format (TR). 🫶

Parameters

UPLO — UPLO is CHARACTER*1
- = 'U': A is upper triangular.
- = 'L': A is lower triangular.
N — N is INTEGER. The order of the matrix A. N >= 0.
AP — AP is COMPLEX*16 array, dimension ( N*(N+1)/2 ). On entry, the upper or lower triangular matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows: if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j; if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.
A — A is COMPLEX*16 array, dimension ( LDA, N ). On exit, the triangular matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of A contains the upper triangular part of the matrix A, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading N-by-N lower triangular part of A contains the lower triangular part of the matrix A, and the strictly upper triangular part of A is not referenced.
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine `ztrcon` (character NORM, character UPLO, character DIAG, integer N, complex16, dimension( lda, ) A, integer LDA, double precision RCOND, complex16, dimension( ) WORK, double precision, dimension( * ) RWORK, integer INFO) 💜

ZTRCON — the vibe check for your triangular matrix. 💅

Purpose

ZTRCON estimates the reciprocal of the condition number of a triangular matrix A, in either the 1-norm or the infinity-norm.

The norm of A is computed and an estimate is obtained for norm(inv(A)), then the reciprocal of the condition number is computed as

   RCOND = 1 / ( norm(A) * norm(inv(A)) ).

Parameters

NORM — NORM is CHARACTER*1. Specifies whether the 1-norm condition number or the infinity-norm condition number is required:
- = '1' or 'O': 1-norm;
- = 'I': Infinity-norm.
UPLO — UPLO is CHARACTER*1
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
DIAG — DIAG is CHARACTER*1
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — N is INTEGER. The order of the matrix A. N >= 0.
A — A is COMPLEX*16 array, dimension (LDA,N). The triangular matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading N-by-N lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced. If DIAG = 'U', the diagonal elements of A are also not referenced and are assumed to be 1.
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
RCOND — RCOND is DOUBLE PRECISION. The reciprocal of the condition number of the matrix A, computed as RCOND = 1/(norm(A) * norm(inv(A))).
WORK — WORK is COMPLEX*16 array, dimension (2*N)
RWORK — RWORK is DOUBLE PRECISION array, dimension (N)
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

subroutine `ztrevc` (character SIDE, character HOWMNY, logical, dimension( * ) SELECT, integer N, complex16, dimension( ldt, ) T, integer LDT, complex16, dimension( ldvl, ) VL, integer LDVL, complex16, dimension( ldvr, ) VR, integer LDVR, integer MM, integer M, complex16, dimension( ) WORK, double precision, dimension( * ) RWORK, integer INFO) 👑

ZTREVC — eigenvectors, bestie. this is THE one. 🔥

Purpose

ZTREVC computes some or all of the right and/or left eigenvectors of a complex upper triangular matrix T. Matrices of this type are produced by the Schur factorization of a complex general matrix: A = Q*T*Q**H, as computed by ZHSEQR.

The right eigenvector x and the left eigenvector y of T corresponding to an eigenvalue w are defined by:

             T*x = w*x,     (y**H)*T = w*(y**H)

where y**H denotes the conjugate transpose of the vector y. The eigenvalues are not input to this routine, but are read directly from the diagonal of T. (not me checking the diagonal instead of asking for params 🙈)

This routine returns the matrices X and/or Y of right and left eigenvectors of T, or the products Q*X and/or Q*Y, where Q is an input matrix. If Q is the unitary factor that reduces a matrix A to Schur form T, then Q*X and Q*Y are the matrices of right and left eigenvectors of A.

Parameters

SIDE — SIDE is CHARACTER*1
- = 'R': compute right eigenvectors only;
- = 'L': compute left eigenvectors only;
- = 'B': compute both right and left eigenvectors.
HOWMNY — HOWMNY is CHARACTER*1
- = 'A': compute all right and/or left eigenvectors;
- = 'B': compute all right and/or left eigenvectors, backtransformed using the matrices supplied in VR and/or VL;
- = 'S': compute selected right and/or left eigenvectors, as indicated by the logical array SELECT.
SELECT — SELECT is LOGICAL array, dimension (N). If HOWMNY = 'S', SELECT specifies the eigenvectors to be computed. The eigenvector corresponding to the j-th eigenvalue is computed if SELECT(j) = .TRUE.. Not referenced if HOWMNY = 'A' or 'B'.
N — N is INTEGER. The order of the matrix T. N >= 0.
T — T is COMPLEX*16 array, dimension (LDT,N). The upper triangular matrix T. T is modified, but restored on exit.
LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,N).
VL — VL is COMPLEX*16 array, dimension (LDVL,MM). On entry, if SIDE = 'L' or 'B' and HOWMNY = 'B', VL must contain an N-by-N matrix Q (usually the unitary matrix Q of Schur vectors returned by ZHSEQR). On exit, if SIDE = 'L' or 'B', VL contains:
- if HOWMNY = 'A', the matrix Y of left eigenvectors of T;
- if HOWMNY = 'B', the matrix Q*Y;
- if HOWMNY = 'S', the left eigenvectors of T specified by SELECT, stored consecutively in the columns of VL, in the same order as their eigenvalues.

Not referenced if SIDE = 'R'.

LDVL — LDVL is INTEGER. The leading dimension of the array VL. LDVL >= 1, and if SIDE = 'L' or 'B', LDVL >= N.
VR
VR — COMPLEX*16 array, dimension (LDVR,MM) 💖 On entry, if SIDE = 'R' or 'B' and HOWMNY = 'B', then bestie, VR has to hold an N-by-N matrix Q (usually that unitary matrix Q of Schur vectors that ZHSEQR hands back). On exit, if SIDE = 'R' or 'B', VR contains:
- if HOWMNY = 'A', the matrix X of right eigenvectors of T;
- if HOWMNY = 'B', the matrix Q*X;
- if HOWMNY = 'S', the right eigenvectors of T specified by SELECT, stored consecutively in the columns of VR, in the same order as their eigenvalues.
- Not referenced if SIDE = 'L' 🙅‍♀️
LDVR — LDVR is INTEGER. The leading dimension of the array VR. LDVR >= 1, and if SIDE = 'R' or 'B'; LDVR >= N. 💅
MM — MM is INTEGER. The number of columns in the arrays VL and/or VR. MM >= M. ✨
M — M is INTEGER. The number of columns in the arrays VL and/or VR actually used to store the eigenvectors. If HOWMNY = 'A' or 'B', M is set to N. Each selected eigenvector occupies one column, no cap. 🎀
WORK — WORK is COMPLEX*16 array, dimension (2*N) 🫶
RWORK — RWORK is DOUBLE PRECISION array, dimension (N) 🌸
INFO — INFO is INTEGER
- = 0: successful exit, we ate 💅
- < 0: if INFO = -i, the i-th argument had an illegal value 😭

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details:

The algorithm used in this program is basically backward (forward) substitution, with scaling to make the the code robust against possible overflow.

Each eigenvector is normalized so that the element of largest magnitude has magnitude 1; here the magnitude of a complex number (x,y) is taken to be |x| + |y|. 🤓

✨ subroutine ztrevc3 ✨

subroutine ztrevc3 (character SIDE, character HOWMNY, logical, dimension( *
) SELECT, integer N, complex*16, dimension( ldt, * ) T, integer LDT,
complex*16, dimension( ldvl, * ) VL, integer LDVL, complex*16,
dimension( ldvr, * ) VR, integer LDVR, integer MM, integer M,
complex*16, dimension( * ) WORK, integer LWORK, double precision,
dimension( * ) RWORK, integer LRWORK, integer INFO)

ZTREVC3 💖

Purpose:

ZTREVC3 computes some or all of the right and/or left eigenvectors of a complex upper triangular matrix T. Matrices of this type are produced by the Schur factorization of a complex general matrix: A = Q*T*Q**H, as computed by ZHSEQR. periodt.

The right eigenvector x and the left eigenvector y of T corresponding to an eigenvalue w are defined by:

T*x = w*x,     (y**H)*T = w*(y**H)

where y**H denotes the conjugate transpose of the vector y. The eigenvalues are not input to this routine, they're just read directly from the diagonal of T. iconic behavior tbh.

This routine returns the matrices X and/or Y of right and left eigenvectors of T, or the products Q*X and/or Q*Y, where Q is an input matrix. If Q is the unitary factor that reduces a matrix A to Schur form T, then Q*X and Q*Y are the matrices of right and left eigenvectors of A. 🌈

This uses a Level 3 BLAS version of the back transformation. 🔥

Parameters

SIDE — SIDE is CHARACTER*1
- = 'R': compute right eigenvectors only;
- = 'L': compute left eigenvectors only;
- = 'B': compute both right and left eigenvectors. both?? we love a versatile icon 💅
HOWMNY — HOWMNY is CHARACTER*1
- = 'A': compute all right and/or left eigenvectors;
- = 'B': compute all right and/or left eigenvectors, backtransformed using the matrices supplied in VR and/or VL;
- = 'S': compute selected right and/or left eigenvectors, as indicated by the logical array SELECT. 🎀
SELECT — SELECT is LOGICAL array, dimension (N). If HOWMNY = 'S', SELECT specifies the eigenvectors to be computed. The eigenvector corresponding to the j-th eigenvalue is computed if SELECT(j) = .TRUE.. Not referenced if HOWMNY = 'A' or 'B'. 🙈
N — N is INTEGER. The order of the matrix T. N >= 0. ✨
T — T is COMPLEX*16 array, dimension (LDT,N). The upper triangular matrix T. T is modified, but restored on exit. bestie's a little messy but she cleans up after herself 🫶
LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,N). 💜
VL — VL is COMPLEX*16 array, dimension (LDVL,MM). On entry, if SIDE = 'L' or 'B' and HOWMNY = 'B', VL must contain an N-by-N matrix Q (usually the unitary matrix Q of Schur vectors returned by ZHSEQR). On exit, if SIDE = 'L' or 'B', VL contains:
- if HOWMNY = 'A', the matrix Y of left eigenvectors of T;
- if HOWMNY = 'B', the matrix Q*Y;
- if HOWMNY = 'S', the left eigenvectors of T specified by SELECT, stored consecutively in the columns of VL, in the same order as their eigenvalues.
- Not referenced if SIDE = 'R'. 😌
LDVL — LDVL is INTEGER. The leading dimension of the array VL. LDVL >= 1, and if SIDE = 'L' or 'B', LDVL >= N. ⭐
VR — VR is COMPLEX*16 array, dimension (LDVR,MM). On entry, if SIDE = 'R' or 'B' and HOWMNY = 'B', VR must contain an N-by-N matrix Q (usually the unitary matrix Q of Schur vectors returned by ZHSEQR). On exit, if SIDE = 'R' or 'B', VR contains:
- if HOWMNY = 'A', the matrix X of right eigenvectors of T;
- if HOWMNY = 'B', the matrix Q*X;
- if HOWMNY = 'S', the right eigenvectors of T specified by SELECT, stored consecutively in the columns of VR, in the same order as their eigenvalues.
- Not referenced if SIDE = 'L'. 💖
LDVR — LDVR is INTEGER. The leading dimension of the array VR. LDVR >= 1, and if SIDE = 'R' or 'B', LDVR >= N. 💅
MM — MM is INTEGER. The number of columns in the arrays VL and/or VR. MM >= M. 🌸
M — M is INTEGER. The number of columns in the arrays VL and/or VR actually used to store the eigenvectors. If HOWMNY = 'A' or 'B', M is set to N. Each selected eigenvector occupies one column. 🎀
WORK — WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)) 🦋
LWORK — LWORK is INTEGER. The dimension of array WORK. LWORK >= max(1,2*N). For optimum performance, LWORK >= N + 2*N*NB, where NB is the optimal blocksize.

RWORK — RWORK is DOUBLE PRECISION array, dimension (LRWORK) 🌈
LRWORK — LRWORK is INTEGER. The dimension of array RWORK. LRWORK >= max(1,N).

If LRWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the RWORK array, returns this value as the first entry of the RWORK array, and no error message related to LRWORK is issued by XERBLA. 💜

INFO — INFO is INTEGER
- = 0: successful exit, we ate 💅
- < 0: if INFO = -i, the i-th argument had an illegal value 😭

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details:

The algorithm used in this program is basically backward (forward) substitution, with scaling to make the the code robust against possible overflow.

Each eigenvector is normalized so that the element of largest magnitude has magnitude 1; here the magnitude of a complex number (x,y) is taken to be |x| + |y|. 🤓

✨ subroutine ztrexc ✨

subroutine ztrexc (character COMPQ, integer N, complex*16, dimension( ldt, *
) T, integer LDT, complex*16, dimension( ldq, * ) Q, integer LDQ,
integer IFST, integer ILST, integer INFO)

ZTREXC 🦋

Purpose:

ZTREXC reorders the Schur factorization of a complex matrix A = Q*T*Q**H, so that the diagonal element of T with row index IFST is moved to row ILST. no cap, just straight up rearranging 💅

The Schur form T is reordered by a unitary similarity transformation Z**H*T*Z, and optionally the matrix Q of Schur vectors is updated by postmultplying it with Z. ✨

Parameters

COMPQ — COMPQ is CHARACTER*1
- = 'V': update the matrix Q of Schur vectors;
- = 'N': do not update Q. 🎀
N — N is INTEGER. The order of the matrix T. N >= 0. If N == 0 arguments ILST and IFST may be any value. zero rows?? then honestly do whatever bestie, it's a free country 🙈
T — T is COMPLEX*16 array, dimension (LDT,N). On entry, the upper triangular matrix T. On exit, the reordered upper triangular matrix. glow up 💖
LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,N). ⭐
Q — Q is COMPLEX*16 array, dimension (LDQ,N). On entry, if COMPQ = 'V', the matrix Q of Schur vectors. On exit, if COMPQ = 'V', Q has been postmultiplied by the unitary transformation matrix Z which reorders T. If COMPQ = 'N', Q is not referenced. 🫶
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= 1, and if COMPQ = 'V', LDQ >= max(1,N). 🌸
IFST — IFST is INTEGER 💜
ILST — ILST is INTEGER 🌈
IFST — bestie, this is where you tell it which diagonal element of T to move where. The element with row index IFST gets moved to row ILST by a sequence of transpositions between adjacent elements (little swaps, one step at a time, no teleporting 💅). Constraints: 1 <= IFST <= N; 1 <= ILST <= N.
INFO — INTEGER, the receipts:
- = 0: successful exit, we ate and left no crumbs ✨
- < 0: if INFO = -i, the i-th argument had an illegal value 🙈

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🦋 subroutine `ztrrfs` — ZTRRFS 🦋

subroutine ztrrfs (character UPLO, character TRANS, character DIAG, integer
    N, integer NRHS, complex*16, dimension( lda, * ) A, integer LDA,
    complex*16, dimension( ldb, * ) B, integer LDB, complex*16, dimension(
    ldx, * ) X, integer LDX, double precision, dimension( * ) FERR, double
    precision, dimension( * ) BERR, complex*16, dimension( * ) WORK, double
    precision, dimension( * ) RWORK, integer INFO)

✨ Purpose

ZTRRFS is the vibe-check bestie for your linear system 💖 It hands you error bounds and backward error estimates for the solution to a system of linear equations with a triangular coefficient matrix.

Heads up, no cap: the solution matrix X must be computed by ZTRTRS or some other means before you walk into this routine. ZTRRFS does not do iterative refinement — because doing so cannot improve the backward error. It said what it said. 💅

🌸 Parameters

UPLO — UPLO is CHARACTER*1
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
TRANS — TRANS is CHARACTER*1. Specifies the form of the system of equations:
- = 'N': A * X = B (No transpose)
- = 'T': A**T * X = B (Transpose)
- = 'C': A**H * X = B (Conjugate transpose)
DIAG — DIAG is CHARACTER*1
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — N is INTEGER. The order of the matrix A. N >= 0.
NRHS — NRHS is INTEGER. The number of right hand sides, i.e., the number of columns of the matrices B and X. NRHS >= 0.
A — A is COMPLEX*16 array, dimension (LDA,N). The triangular matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading N-by-N lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced. If DIAG = 'U', the diagonal elements of A are also not referenced and are assumed to be 1. (Iconic behaviour honestly, skipping the boring bits 😌)
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
B — B is COMPLEX*16 array, dimension (LDB,NRHS). The right hand side matrix B.
LDB — LDB is INTEGER. The leading dimension of the array B. LDB >= max(1,N).
X — X is COMPLEX*16 array, dimension (LDX,NRHS). The solution matrix X.
LDX — LDX is INTEGER. The leading dimension of the array X. LDX >= max(1,N).
FERR — FERR is DOUBLE PRECISION array, dimension (NRHS). The estimated forward error bound for each solution vector X(j) (the j-th column of the solution matrix X). If XTRUE is the true solution corresponding to X(j), FERR(j) is an estimated upper bound for the magnitude of the largest element in (X(j) - XTRUE) divided by the magnitude of the largest element in X(j). The estimate is as reliable as the estimate for RCOND, and is almost always a slight overestimate of the true error. (It's giving "overprotective bestie" energy 🫶)
BERR — BERR is DOUBLE PRECISION array, dimension (NRHS). The componentwise relative backward error of each solution vector X(j) (i.e., the smallest relative change in any element of A or B that makes X(j) an exact solution).
WORK — WORK is COMPLEX*16 array, dimension (2*N)
RWORK — RWORK is DOUBLE PRECISION array, dimension (N)
INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌈 subroutine `ztrsen` — ZTRSEN 🌈

subroutine ztrsen (character JOB, character COMPQ, logical, dimension( * )
    SELECT, integer N, complex*16, dimension( ldt, * ) T, integer LDT,
    complex*16, dimension( ldq, * ) Q, integer LDQ, complex*16, dimension( *
    ) W, integer M, double precision S, double precision SEP, complex*16,
    dimension( * ) WORK, integer LWORK, integer INFO)

✨ Purpose

ZTRSEN reorders the Schur factorization of a complex matrix A = Q*T*Q**H, so that a selected cluster of eigenvalues shows up in the leading positions on the diagonal of the upper triangular matrix T, and the leading columns of Q form an orthonormal basis of the corresponding right invariant subspace. Front row seats for the chosen eigenvalues, periodt 👑

Optionally the routine computes the reciprocal condition numbers of the cluster of eigenvalues and/or the invariant subspace. Very "and I also did your homework" of it 💅

🌸 Parameters

JOB — JOB is CHARACTER*1. Specifies whether condition numbers are required for the cluster of eigenvalues (S) or the invariant subspace (SEP):
- = 'N': none;
- = 'E': for eigenvalues only (S);
- = 'V': for invariant subspace only (SEP);
- = 'B': for both eigenvalues and invariant subspace (S and SEP).
COMPQ — COMPQ is CHARACTER*1
- = 'V': update the matrix Q of Schur vectors;
- = 'N': do not update Q.
SELECT — SELECT is LOGICAL array, dimension (N). SELECT specifies the eigenvalues in the selected cluster. To select the j-th eigenvalue, SELECT(j) must be set to .TRUE.. (Pick your faves, bestie 🎀)
N — N is INTEGER. The order of the matrix T. N >= 0.
T — T is COMPLEX*16 array, dimension (LDT,N). On entry, the upper triangular matrix T. On exit, T is overwritten by the reordered matrix T, with the selected eigenvalues as the leading diagonal elements.
LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,N).
Q — Q is COMPLEX*16 array, dimension (LDQ,N). On entry, if COMPQ = 'V', the matrix Q of Schur vectors. On exit, if COMPQ = 'V', Q has been postmultiplied by the unitary transformation matrix which reorders T; the leading M columns of Q form an orthonormal basis for the specified invariant subspace. If COMPQ = 'N', Q is not referenced.
LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= 1; and if COMPQ = 'V', LDQ >= N.
W — W is COMPLEX*16 array, dimension (N). The reordered eigenvalues of T, in the same order as they appear on the diagonal of T.
M — M is INTEGER. The dimension of the specified invariant subspace. 0 <= M <= N.
S — S is DOUBLE PRECISION. If JOB = 'E' or 'B', S is a lower bound on the reciprocal condition number for the selected cluster of eigenvalues. S cannot underestimate the true reciprocal condition number by more than a factor of sqrt(N). If M = 0 or N, S = 1. If JOB = 'N' or 'V', S is not referenced.
SEP — SEP is DOUBLE PRECISION. If JOB = 'V' or 'B', SEP is the estimated reciprocal condition number of the specified invariant subspace. If M = 0 or N, SEP = norm(T). If JOB = 'N' or 'E', SEP is not referenced.
WORK — WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. (It's a little spy that tells you the right size 🔍)
LWORK — LWORK is INTEGER. The dimension of the array WORK.
- If JOB = 'N', LWORK >= 1;
- if JOB = 'E', LWORK = max(1,M*(N-M));
- if JOB = 'V' or 'B', LWORK >= max(1,2*M*(N-M)).

INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

💫 Further Details

ZTRSEN first collects the selected eigenvalues by computing a unitary transformation Z to move them to the top left corner of T. In other words, the selected eigenvalues are the eigenvalues of T11 in:

Z**H * T * Z = ( T11 T12 ) n1
               (  0  T22 ) n2
                  n1  n2

where N = n1+n2. The first n1 columns of Z span the specified invariant subspace of T.

If T has been obtained from the Schur factorization of a matrix A = Q*T*Q**H, then the reordered Schur factorization of A is given by A = (Q*Z)*(Z**H*T*Z)*(Q*Z)**H, and the first n1 columns of Q*Z span the corresponding invariant subspace of A. (Glow-up transformation, honestly ✨)

The reciprocal condition number of the average of the eigenvalues of T11 may be returned in S. S lies between 0 (very badly conditioned) and 1 (very well conditioned). It is computed as follows. First we compute R so that

P = ( I  R ) n1
    ( 0  0 ) n2
      n1 n2

is the projector on the invariant subspace associated with T11. R is the solution of the Sylvester equation:

T11*R - R*T22 = T12.

Let F-norm(M) mean the Frobenius-norm of M, and let 2-norm(M) mean the two-norm of M. Kk so then S gets computed as this lower bound right here:

(1 + F-norm(R)**2)**(-1/2)

…on the reciprocal of 2-norm(P), aka the true reciprocal condition number. And bestie, S literally cannot underestimate 1 / 2-norm(P) by more than a factor of sqrt(N). That's the deal. ✨

An approximate error bound for the computed average of the eigenvalues of T11 is

EPS * norm(T) / S

where EPS is the machine precision. (yes it always comes back to EPS, it's giving main character energy)

The reciprocal condition number of the right invariant subspace spanned by the first n1 columns of Z (or of Q*Z) is returned in SEP. And SEP is defined as the separation of T11 and T22:

sep( T11, T22 ) = sigma-min( C )

where sigma-min(C) is the smallest singular value of the n1*n2-by-n1*n2 matrix

C  = kprod( I(n2), T11 ) - kprod( transpose(T22), I(n1) )

I(m) is an m by m identity matrix, and kprod denotes the Kronecker product. We estimate sigma-min(C) by the reciprocal of an estimate of the 1-norm of inverse(C). And ngl, the true reciprocal 1-norm of inverse(C) cannot differ from sigma-min(C) by more than a factor of sqrt(n1*n2). 🎀

When SEP is small, small changes in T can cause big changes in the invariant subspace. An approximate bound on the maximum angular error in the computed right invariant subspace is

EPS * norm(T) / SEP

🦋 subroutine `ztrsna` 🦋

subroutine ztrsna (character JOB, character HOWMNY, logical, dimension( * )
    SELECT, integer N, complex*16, dimension( ldt, * ) T, integer LDT,
    complex*16, dimension( ldvl, * ) VL, integer LDVL, complex*16,
    dimension( ldvr, * ) VR, integer LDVR, double precision, dimension( * )
    S, double precision, dimension( * ) SEP, integer MM, integer M,
    complex*16, dimension( ldwork, * ) WORK, integer LDWORK, double
    precision, dimension( * ) RWORK, integer INFO)

ZTRSNA

✨ Purpose ✨

ZTRSNA estimates reciprocal condition numbers for specified eigenvalues and/or right eigenvectors of a complex upper triangular matrix T (or of any matrix Q*T*Q**H with Q unitary). iconic behavior tbh

🌸 Parameters 🌸

JOB — JOB is CHARACTER*1. Tells us whether we want condition numbers for eigenvalues (S) or eigenvectors (SEP):
- = 'E': for eigenvalues only (S);
- = 'V': for eigenvectors only (SEP);
- = 'B': for both eigenvalues and eigenvectors (S and SEP). 💅
HOWMNY — HOWMNY is CHARACTER*1:
- = 'A': compute condition numbers for all eigenpairs;
- = 'S': compute condition numbers for selected eigenpairs specified by the array SELECT.
SELECT — SELECT is LOGICAL array, dimension (N). If HOWMNY = 'S', SELECT specifies the eigenpairs for which condition numbers are required. To select condition numbers for the j-th eigenpair, SELECT(j) must be set to .TRUE.. If HOWMNY = 'A', SELECT is not referenced. (she's off duty, don't @ her)
N — N is INTEGER. The order of the matrix T. N >= 0.
T — T is COMPLEX*16 array, dimension (LDT,N). The upper triangular matrix T. 🔺
LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,N).
VL — VL is COMPLEX*16 array, dimension (LDVL,M). If JOB = 'E' or 'B', VL must contain left eigenvectors of T (or of any Q*T*Q**H with Q unitary), corresponding to the eigenpairs specified by HOWMNY and SELECT. The eigenvectors must be stored in consecutive columns of VL, as returned by ZHSEIN or ZTREVC. If JOB = 'V', VL is not referenced. 🫶
LDVL — LDVL is INTEGER. The leading dimension of the array VL. LDVL >= 1; and if JOB = 'E' or 'B', LDVL >= N.
VR — VR is COMPLEX*16 array, dimension (LDVR,M). If JOB = 'E' or 'B', VR must contain right eigenvectors of T (or of any Q*T*Q**H with Q unitary), corresponding to the eigenpairs specified by HOWMNY and SELECT. The eigenvectors must be stored in consecutive columns of VR, as returned by ZHSEIN or ZTREVC. If JOB = 'V', VR is not referenced. ✨
LDVR — LDVR is INTEGER. The leading dimension of the array VR. LDVR >= 1; and if JOB = 'E' or 'B', LDVR >= N.
S — S is DOUBLE PRECISION array, dimension (MM). If JOB = 'E' or 'B', the reciprocal condition numbers of the selected eigenvalues, stored in consecutive elements of the array. So lowkey S(j), SEP(j), and the j-th columns of VL and VR all correspond to the same eigenpair (but not in general the j-th eigenpair, unless all eigenpairs are selected — the way that gotcha is REAL 😭). If JOB = 'V', S is not referenced.
SEP — SEP is DOUBLE PRECISION array, dimension (MM). If JOB = 'V' or 'B', the estimated reciprocal condition numbers of the selected eigenvectors, stored in consecutive elements of the array. If JOB = 'E', SEP is not referenced. 💜
MM — MM is INTEGER. The number of elements in the arrays S (if JOB = 'E' or 'B') and/or SEP (if JOB = 'V' or 'B'). MM >= M.
M — M is INTEGER. The number of elements of the arrays S and/or SEP actually used to store the estimated condition numbers. If HOWMNY = 'A', M is set to N. 🎀
WORK — WORK is COMPLEX*16 array, dimension (LDWORK,N+6). If JOB = 'E', WORK is not referenced.
LDWORK — LDWORK is INTEGER. The leading dimension of the array WORK. LDWORK >= 1; and if JOB = 'V' or 'B', LDWORK >= N.
RWORK — RWORK is DOUBLE PRECISION array, dimension (N). If JOB = 'E', RWORK is not referenced.
INFO — INFO is INTEGER:
- = 0: successful exit ✅
- < 0: if INFO = -i, the i-th argument had an illegal value ❌

👑 Author 👑

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🔥 Further Details 🔥

The reciprocal of the condition number of an eigenvalue lambda is defined as

S(lambda) = |v**H*u| / (norm(u)*norm(v))

where u and v are the right and left eigenvectors of T corresponding to lambda; v**H denotes the conjugate transpose of v, and norm(u) denotes the Euclidean norm. These reciprocal condition numbers always lie between zero (very badly conditioned) and one (very well conditioned). If n = 1, S(lambda) is defined to be 1. periodt.

An approximate error bound for a computed eigenvalue W(i) is given by

EPS * norm(T) / S(i)

where EPS is the machine precision.

The reciprocal of the condition number of the right eigenvector u corresponding to lambda is defined as follows. Suppose

T = ( lambda  c  )
    (   0    T22 )

Then the reciprocal condition number is

SEP( lambda, T22 ) = sigma-min( T22 - lambda*I )

where sigma-min denotes the smallest singular value. We approximate the smallest singular value by the reciprocal of an estimate of the one-norm of the inverse of T22 - lambda*I. If n = 1, SEP(1) is defined to be abs(T(1,1)). 🦋

An approximate error bound for a computed right eigenvector VR(i) is given by

EPS * norm(T) / SEP(i)

🧚 subroutine `ztrti2` 🧚

subroutine ztrti2 (character UPLO, character DIAG, integer N, complex*16,
    dimension( lda, * ) A, integer LDA, integer INFO)

ZTRTI2 computes the inverse of a triangular matrix (unblocked algorithm).

✨ Purpose ✨

ZTRTI2 computes the inverse of a complex upper or lower triangular matrix.

This is the Level 2 BLAS version of the algorithm. 🎀

🌸 Parameters 🌸

UPLO — UPLO is CHARACTER*1. Specifies whether the matrix A is upper or lower triangular:
- = 'U': Upper triangular
- = 'L': Lower triangular
DIAG — DIAG is CHARACTER*1. Specifies whether or not the matrix A is unit triangular:
- = 'N': Non-unit triangular
- = 'U': Unit triangular
N — N is INTEGER. The order of the matrix A. N >= 0.
A — A is COMPLEX*16 array, dimension (LDA,N). On entry, the triangular matrix A. If UPLO = 'U', the leading n by n upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading n by n lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced. If DIAG = 'U', the diagonal elements of A are also not referenced and are assumed to be 1.

On exit, the (triangular) inverse of the original matrix, in the same storage format. 💅

LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
INFO — INFO is INTEGER:
- = 0: successful exit ✅
- < 0: if INFO = -k, the k-th argument had an illegal value ❌

👑 Author 👑

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🌈 subroutine `ztrtri` 🌈

subroutine ztrtri (character UPLO, character DIAG, integer N, complex*16,
    dimension( lda, * ) A, integer LDA, integer INFO)

ZTRTRI

✨ Purpose ✨

ZTRTRI computes the inverse of a complex upper or lower triangular matrix A.

This is the Level 3 BLAS version of the algorithm. 🔥

🌸 Parameters 🌸

UPLO — UPLO is CHARACTER*1:
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
DIAG — DIAG is CHARACTER*1:
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N
N — INTEGER bestie 💫 the order of the matrix A. N >= 0, that's the law.
A — COMPLEX*16 array, dimension (LDA,N). On entry, this is the triangular matrix A. So here's the tea ☕: if UPLO = 'U', the leading N-by-N upper triangular part of the array A holds the upper triangular matrix, and the strictly lower triangular part of A is not referenced (she's just there, unbothered, not read, not touched). If UPLO = 'L', it's the mirror situation: the leading N-by-N lower triangular part of the array A holds the lower triangular matrix, and the strictly upper triangular part of A is not referenced. And if DIAG = 'U', the diagonal elements of A are also not referenced and are assumed to be 1. On exit, you get the (triangular) inverse of the original matrix, in the same storage format. She did the math and ate 💅
LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,N).
INFO — INTEGER. the receipts, bestie:
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value 🙈
- > 0: if INFO = i, A(i,i) is exactly zero. The triangular matrix is singular and its inverse can not be computed. 💀

🫶 Author 🫶

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🦋 subroutine `ztrtrs` (character `UPLO`, character `TRANS`, character `DIAG`, integer `N`, integer `NRHS`, complex16, dimension( `lda`, ) `A`, integer `LDA`, complex16, dimension( `ldb`, ) `B`, integer `LDB`, integer `INFO`) 🦋

ZTRTRS

✨ Purpose: ✨

            ZTRTRS solves a triangular system of the form

               A * X = B,  A**T * X = B,  or  A**H * X = B,

            where A is a triangular matrix of order N, and B is an N-by-NRHS
            matrix.  A check is made to verify that A is nonsingular.

Like, she solves the system, and she also checks that A isn't singular, because she's thorough and she's not about to hand you nonsense. 👑

💖 Parameters 💖

UPLO — CHARACTER*1
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
TRANS — CHARACTER*1. Specifies the form of the system of equations:
- = 'N': A * X = B (No transpose)
- = 'T': A**T * X = B (Transpose)
- = 'C': A**H * X = B (Conjugate transpose)
DIAG — CHARACTER*1
- = 'N': A is non-unit triangular;
- = 'U': A is unit triangular.
N — INTEGER. The order of the matrix A. N >= 0.
NRHS — INTEGER. The number of right hand sides, i.e., the number of columns of the matrix B. NRHS >= 0.
A — COMPLEX*16 array, dimension (LDA,N). The triangular matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading N-by-N lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced. If DIAG = 'U', the diagonal elements of A are also not referenced and are assumed to be 1. 🎀
LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,N).
B — COMPLEX*16 array, dimension (LDB,NRHS). On entry, the right hand side matrix B. On exit, if INFO = 0, the solution matrix X. glow-up moment ✨
LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,N).
INFO — INTEGER
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value 🙈
- > 0: if INFO = i, the i-th diagonal element of A is zero, indicating that the matrix is singular and the solutions X have not been computed. no solution for you, bestie 😭

🫶 Author 🫶

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌸 subroutine `ztrttf` (character `TRANSR`, character `UPLO`, integer `N`, complex16, dimension( 0: `lda`-1, 0: ) `A`, integer `LDA`, complex16, dimension( 0: ) `ARF`, integer `INFO`) 🌸

ZTRTTF copies a triangular matrix from the standard full format (TR) to the rectangular full packed format (TF).

✨ Purpose: ✨

            ZTRTTF copies a triangular matrix A from standard full format (TR)
            to rectangular full packed format (TF) .

Format glow-up, but make it triangular. 🦋

💖 Parameters 💖

TRANSR — CHARACTER*1
- = 'N': ARF in Normal mode is wanted;
- = 'C': ARF in Conjugate Transpose mode is wanted;
UPLO — CHARACTER*1
- = 'U': A is upper triangular;
- = 'L': A is lower triangular.
N — INTEGER. The order of the matrix A. N >= 0.
A — COMPLEX*16 array, dimension ( LDA, N ). On entry, the triangular matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of the array A contains the upper triangular matrix, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading N-by-N lower triangular part of the array A contains the lower triangular matrix, and the strictly upper triangular part of A is not referenced.
LDA — INTEGER. The leading dimension of the matrix A. LDA >= max(1,N).
ARF — COMPLEX*16 array, dimension ( N*(N+1)/2 ). On exit, the upper or lower triangular matrix A stored in RFP format. For a further discussion see Notes below. 👀
INFO — INTEGER
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value 🙈

🫶 Author 🫶

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details: 🔍

Okay bestie, this is the diagram era 📐 get comfy, because we're about to look at exactly how the packing works. First up: Standard Packed Format when N is even. Example where N = 6.

             We first consider Standard Packed Format when N is even.
             We give an example where N = 6.

                 AP is Upper             AP is Lower

              00 01 02 03 04 05       00
                 11 12 13 14 15       10 11
                    22 23 24 25       20 21 22
                       33 34 35       30 31 32 33
                          44 45       40 41 42 43 44
                             55       50 51 52 53 54 55

Now, let TRANSR = 'N'. RFP holds AP as follows: for UPLO = 'U' the upper trapezoid A(0:5,0:2) consists of the last three columns of AP upper. The lower triangle A(4:6,0:2) consists of conjugate-transpose of the first three columns of AP upper. For UPLO = 'L' the lower trapezoid A(1:6,0:2) consists of the first three columns of AP lower. The upper triangle A(0:2,0:2) consists of conjugate-transpose of the last three columns of AP lower. To denote conjugate we place -- above the element. This covers the case N even and TRANSR = 'N'.

                    RFP A                   RFP A

                                           -- -- --
                   03 04 05                33 43 53
                                              -- --
                   13 14 15                00 44 54
                                                 --
                   23 24 25                10 11 55

                   33 34 35                20 21 22
                   --
                   00 44 45                30 31 32
                   -- --
                   01 11 55                40 41 42
                   -- -- --
                   02 12 22                50 51 52

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- -- --                -- -- -- -- -- --
                03 13 23 33 00 01 02    33 00 10 20 30 40 50
                -- -- -- -- --                -- -- -- -- --
                04 14 24 34 44 11 12    43 44 11 21 31 41 51
                -- -- -- -- -- --                -- -- -- --
                05 15 25 35 45 55 22    53 54 55 22 32 42 52

✨ and now the odd case ✨ We next consider Standard Packed Format when N is odd. Example where N = 5.

             We next  consider Standard Packed Format when N is odd.
             We give an example where N = 5.

                AP is Upper                 AP is Lower

              00 01 02 03 04              00
                 11 12 13 14              10 11
                    22 23 24              20 21 22
                       33 34              30 31 32 33
                          44              40 41 42 43 44

                    RFP A                   RFP A

                                              -- --
                   02 03 04                00 33 43
                                                 --
                   12 13 14                10 11 44

                   22 23 24                20 21 22
                   --
                   00 33 34                30 31 32
                   -- --
                   01 11 44                40 41 42

Now let TRANSR = 'C'. RFP A in both UPLO cases is just the conjugate-transpose of RFP A above. One therefore gets:

                      RFP A                   RFP A

                -- -- --                   -- -- -- -- -- --
                02 12 22 00 01             00 10 20 30 40 50
                -- -- -- --                   -- -- -- -- --
                03 13 23 33 11             33 11 21 31 41 51
                -- -- -- -- --                   -- -- -- --
                04 14 24 34 44             43 44 22 32 42 52

🎀 subroutine `ztrttp` (character `UPLO`, integer `N`, complex16, dimension( `lda`, ) `A`, integer `LDA`, complex16, dimension( ) `AP`, integer `INFO`) 🎀

ZTRTTP copies a triangular matrix from the standard full format (TR) to the standard packed format (TP).

✨ Purpose: ✨

            ZTRTTP copies a triangular matrix A from full format (TR) to standard
            packed format (TP).

💖 Parameters 💖

UPLO —

UPLO is CHARACTER*1 — okay bestie, this is the shape selector, no cap 💅:

= 'U': A is upper triangular;
= 'L': A is lower triangular.

N is INTEGER — the order of the matrices AP and A. N >= 0. ✨ periodt.

A is COMPLEX*16 array, dimension (LDA,N) — On entry, the triangular matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of A contains the upper triangular part of the matrix A, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading N-by-N lower triangular part of A contains the lower triangular part of the matrix A, and the strictly upper triangular part of A is not referenced. 🦋

LDA is INTEGER — The leading dimension of the array A. LDA >= max(1,N). 💖

AP is COMPLEX*16 array, dimension ( N*(N+1)/2 ), — On exit, the upper or lower triangular matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows: 🌸

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2n-j)/2) = A(i,j) for j<=i<=n.

INFO is INTEGER 😭

= 0: successful exit
< 0: if INFO = -i, the i-th argument had an illegal value

Author 👑

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

`subroutine ztzrzf` ✨

   subroutine ztzrzf (integer M, integer N, complex*16, dimension( lda, * ) A,
       integer LDA, complex*16, dimension( * ) TAU, complex*16, dimension( * )
       WORK, integer LWORK, integer INFO)
       ZTZRZF

`ZTZRZF` 💅

Purpose: 🔥

ZTZRZF reduces the M-by-N ( M<=N ) complex upper trapezoidal matrix A to upper triangular form by means of unitary transformations.

The upper trapezoidal matrix A is factored as

   A = ( R  0 ) * Z,

where Z is an N-by-N unitary matrix and R is an M-by-M upper triangular matrix. 🌈

Parameters 🎀

M is INTEGER — The number of rows of the matrix A. M >= 0. 💖
N is INTEGER — The number of columns of the matrix A. N >= M. ✨
A is COMPLEX*16 array, dimension (LDA,N) — On entry, the leading M-by-N upper trapezoidal part of the array A must contain the matrix to be factorized. On exit, the leading M-by-M upper triangular part of A contains the upper triangular matrix R, and elements M+1 to N of the first M rows of A, with the array TAU, represent the unitary matrix Z as a product of M elementary reflectors. 🦋
LDA is INTEGER — The leading dimension of the array A. LDA >= max(1,M). 💅
TAU is COMPLEX*16 array, dimension (M) — The scalar factors of the elementary reflectors. ⭐
WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)) — On exit, if INFO = 0, WORK(1) returns the optimal LWORK. 🫶
LWORK is INTEGER — The dimension of the array WORK. LWORK >= max(1,M). For optimum performance LWORK >= M*NB, where NB is the optimal blocksize. 👑

INFO is INTEGER 😭
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

Author 👑

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

Contributors: 🫶

A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville, USA

Further Details: 🧚

The N-by-N matrix Z can be computed by

   Z =  Z(1)*Z(2)* ... *Z(M)

where each N-by-N Z(k) is given by

   Z(k) = I - tau(k)*v(k)*v(k)**H

with v(k) is the kth row vector of the M-by-N matrix

   V = ( I   A(:,M+1:N) )

I is the M-by-M identity matrix, A(:,M+1:N) is the output stored in A on exit from ZTZRZF, and tau(k) is the kth element of the array TAU. 💜

`subroutine zunbdb` 🌈

   subroutine zunbdb (character TRANS, character SIGNS, integer M, integer P,
       integer Q, complex*16, dimension( ldx11, * ) X11, integer LDX11,
       complex*16, dimension( ldx12, * ) X12, integer LDX12, complex*16,
       dimension( ldx21, * ) X21, integer LDX21, complex*16, dimension( ldx22,
       * ) X22, integer LDX22, double precision, dimension( * ) THETA, double
       precision, dimension( * ) PHI, complex*16, dimension( * ) TAUP1,
       complex*16, dimension( * ) TAUP2, complex*16, dimension( * ) TAUQ1,
       complex*16, dimension( * ) TAUQ2, complex*16, dimension( * ) WORK,
       integer LWORK, integer INFO)
       ZUNBDB

`ZUNBDB` 👑

Purpose: 🔥

ZUNBDB simultaneously bidiagonalizes the blocks of an M-by-M partitioned unitary matrix X:

                                            [ B11 | B12 0  0 ]
                [ X11 | X12 ]   [ P1 |    ] [  0  |  0 -I  0 ] [ Q1 |    ]**H
            X = [-----------] = [---------] [----------------] [---------]   .
                [ X21 | X22 ]   [    | P2 ] [ B21 | B22 0  0 ] [    | Q2 ]
                                            [  0  |  0  0  I ]

X11 is P-by-Q. Q must be no larger than P, M-P, or M-Q. (If this is not the case, then X must be transposed and/or permuted. This can be done in constant time using the TRANS and SIGNS options. See ZUNCSD for details.) 🌸

The unitary matrices P1, P2, Q1, and Q2 are P-by-P, (M-P)-by-(M-P), Q-by-Q, and (M-Q)-by-(M-Q), respectively. They are represented implicitly by Householder vectors. ✨

B11, B12, B21, and B22 are Q-by-Q bidiagonal matrices represented implicitly by angles THETA, PHI. 💅

Parameters 🎀

TRANS is CHARACTER 🦋
- = 'T': X, U1, U2, V1T, and V2T are stored in row-major order;
- otherwise: X, U1, U2, V1T, and V2T are stored in column-major order.
SIGNS is CHARACTER ⭐
- = 'O': The lower-left block is made nonpositive (the 'other' convention);
- otherwise: The upper-right block is made nonpositive (the 'default' convention).
M is INTEGER — The number of rows and columns in X. 💖
P is INTEGER — The number of rows in X11 and X12. 0 <= P <= M. ✨
Q is INTEGER — The number of columns in X11 and X21. 0 <= Q <= MIN(P,M-P,M-Q). 👑
X11 is COMPLEX*16 array, dimension (LDX11,Q) — On entry, the top-left block of the unitary matrix to be reduced. On exit, the form depends on TRANS: 🦋
- If TRANS = 'N', then
  - the columns of tril(X11) specify reflectors for P1,
  - the rows of triu(X11,1) specify reflectors for Q1;
- else TRANS = 'T', and
  - the rows of triu(X11) specify reflectors for P1,
  - the columns of tril(X11,-1) specify reflectors for Q1.
LDX11 is INTEGER — The leading dimension of X11. If TRANS = 'N', then LDX11 >= P; else LDX11 >= Q. 💅
X12 is COMPLEX*16 array, dimension (LDX12,M-Q) — On entry, the top-right block of the unitary matrix to be reduced. On exit, the form depends on TRANS: 🌸
- If TRANS = 'N', then
  - the rows of triu(X12) specify the first P reflectors for Q2;
- else TRANS = 'T', and
  - the columns of tril(X12) specify the first P reflectors for Q2.
LDX12 is INTEGER — The leading dimension of X12. If TRANS = 'N', then LDX12 >= P; else LDX11 >= M-Q. 😭
X21 is COMPLEX*16 array, dimension (LDX21,Q) — On entry, the bottom-left block of the unitary matrix to be reduced. On exit, the form depends on TRANS: 🦋
- If TRANS = 'N', then
  - the columns of tril(X21) specify reflectors for P2;
- else TRANS = 'T', and
  - the rows of triu(X21) specify reflectors for P2.
LDX21 is INTEGER — The leading dimension of X21. If TRANS = 'N', then LDX21 >= M-P; else LDX21 >= Q. 💖
X22 is COMPLEX*16 array, dimension (LDX22,M-Q) — On entry, the bottom-right block of the unitary matrix to be reduced. On exit, the form depends on TRANS: 🌈
- If TRANS = 'N', then
  - the rows of triu(X22(Q+1:M-P,P+1:M-Q)) specify the last M-P-Q reflectors for Q2,
- else TRANS = 'T', and
  - the columns of tril(X22(P+1:M-Q,Q+1:M-P)) specify the last M-P-Q reflectors for P2.
LDX22 is INTEGER — The leading dimension of X22. If TRANS = 'N', then LDX22 >= M-P; else LDX22 >= M-Q. ✨
THETA is DOUBLE PRECISION array, dimension (Q) — The entries of the bidiagonal blocks B11, B12, B21, B22 can be computed from the angles THETA and PHI. See Further Details. 🫶
PHI is DOUBLE PRECISION array, dimension (Q-1) — The entries of the bidiagonal blocks B11, B12, B21, B22 can be computed from the angles THETA and PHI. See Further Details. 💜
TAUP1 is COMPLEX*16 array, dimension (P) — The scalar factors of the elementary reflectors that define P1. ⭐
TAUP2 is COMPLEX*16 array, dimension (M-P) — The scalar factors of the elementary reflectors that define P2. 🔥
TAUQ1 is COMPLEX*16 array, dimension (Q) — The scalar factors of the elementary reflectors that define Q1. 👑
TAUQ2 💅
TAUQ2 — COMPLEX*16 array, dimension (M-Q). The scalar factors of the elementary reflectors that define Q2. bestie these little guys hold the whole rotation together 💅
WORK — COMPLEX*16 array, dimension (LWORK).
LWORK — INTEGER. The dimension of the array WORK. LWORK >= M-Q.

okay so if LWORK = -1 a workspace query is assumed: the routine only calculates the optimal size of the WORK array, hands it back as the first entry of WORK, and XERBLA will NOT throw any error about LWORK. it's giving "just asking, not doing" ✨

INFO — INTEGER.
- = 0: successful exit, we ate 💖
- < 0: if INFO = -i, the i-th argument had an illegal value. not iconic of that argument ngl 💀

Author 🎀

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details: 🔥

The bidiagonal blocks B11, B12, B21, and B22 are represented implicitly by angles THETA(1), ..., THETA(Q) and PHI(1), ..., PHI(Q-1). B11 and B21 are upper bidiagonal, while B21 and B22 are lower bidiagonal. Every entry in each bidiagonal band is a product of a sine or cosine of a THETA with a sine or cosine of a PHI. See [1] or ZUNCSD for details.

P1, P2, Q1, and Q2 are represented as products of elementary reflectors. See ZUNCSD for details on generating P1, P2, Q1, and Q2 using ZUNGQR and ZUNGLQ.

References: 📚

[1] Brian D. Sutton. Computing the complete CS decomposition. Numer. Algorithms, 50(1):33-65, 2009.

🌈 `subroutine zunbdb1` 🌈

subroutine zunbdb1 (integer M, integer P, integer Q, complex*16,
    dimension(ldx11,*) X11, integer LDX11, complex*16, dimension(ldx21,*)
    X21, integer LDX21, double precision, dimension(*) THETA, double
    precision, dimension(*) PHI, complex*16, dimension(*) TAUP1, complex*16,
    dimension(*) TAUP2, complex*16, dimension(*) TAUQ1, complex*16,
    dimension(*) WORK, integer LWORK, integer INFO)

ZUNBDB1

Purpose: 💫

ZUNBDB1 simultaneously bidiagonalizes the blocks of a tall and skinny matrix X with orthonomal columns:

                           [ B11 ]
     [ X11 ]   [ P1 |    ] [  0  ]
     [-----] = [---------] [-----] Q1**T .
     [ X21 ]   [    | P2 ] [ B21 ]
                           [  0  ]

X11 is P-by-Q, and X21 is (M-P)-by-Q. Q must be no larger than P, M-P, or M-Q. Routines ZUNBDB2, ZUNBDB3, and ZUNBDB4 handle cases in which Q is not the minimum dimension.

The unitary matrices P1, P2, and Q1 are P-by-P, (M-P)-by-(M-P), and (M-Q)-by-(M-Q), respectively. They are represented implicitly by Householder vectors.

B11 and B12 are Q-by-Q bidiagonal matrices represented implicitly by angles THETA, PHI.

Parameters 🦋

M — INTEGER. The number of rows X11 plus the number of rows in X21.
P — INTEGER. The number of rows in X11. 0 <= P <= M.
Q — INTEGER. The number of columns in X11 and X21. 0 <= Q <= MIN(P,M-P,M-Q).
X11 — COMPLEX*16 array, dimension (LDX11,Q). On entry, the top block of the matrix X to be reduced. On exit, the columns of tril(X11) specify reflectors for P1 and the rows of triu(X11,1) specify reflectors for Q1.
LDX11 — INTEGER. The leading dimension of X11. LDX11 >= P.
X21 — COMPLEX*16 array, dimension (LDX21,Q). On entry, the bottom block of the matrix X to be reduced. On exit, the columns of tril(X21) specify reflectors for P2.
LDX21 — INTEGER. The leading dimension of X21. LDX21 >= M-P.
THETA — DOUBLE PRECISION array, dimension (Q). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details.
PHI — DOUBLE PRECISION array, dimension (Q-1). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details.
TAUP1 — COMPLEX*16 array, dimension (P). The scalar factors of the elementary reflectors that define P1.
TAUP2 — COMPLEX*16 array, dimension (M-P). The scalar factors of the elementary reflectors that define P2.
TAUQ1 — COMPLEX*16 array, dimension (Q). The scalar factors of the elementary reflectors that define Q1.
WORK — COMPLEX*16 array, dimension (LWORK).
LWORK — INTEGER. The dimension of the array WORK. LWORK >= M-Q.

if LWORK = -1, a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. no drama, no XERBLA yelling 💖

INFO — INTEGER.
- = 0: successful exit.
- < 0: if INFO = -i, the i-th argument had an illegal value.

Author 🎀

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details: 🔥

The upper-bidiagonal blocks B11, B21 are represented implicitly by angles THETA(1), ..., THETA(Q) and PHI(1), ..., PHI(Q-1). Every entry in each bidiagonal band is a product of a sine or cosine of a THETA with a sine or cosine of a PHI. See [1] or ZUNCSD for details.

P1, P2, and Q1 are represented as products of elementary reflectors. See ZUNCSD2BY1 for details on generating P1, P2, and Q1 using ZUNGQR and ZUNGLQ.

References: 📚

[1] Brian D. Sutton. Computing the complete CS decomposition. Numer. Algorithms, 50(1):33-65, 2009.

✨ `subroutine zunbdb2` ✨

subroutine zunbdb2 (integer M, integer P, integer Q, complex*16,
    dimension(ldx11,*) X11, integer LDX11, complex*16, dimension(ldx21,*)
    X21, integer LDX21, double precision, dimension(*) THETA, double
    precision, dimension(*) PHI, complex*16, dimension(*) TAUP1, complex*16,
    dimension(*) TAUP2, complex*16, dimension(*) TAUQ1, complex*16,
    dimension(*) WORK, integer LWORK, integer INFO)

ZUNBDB2

Purpose: 💫

ZUNBDB2 simultaneously bidiagonalizes the blocks of a tall and skinny matrix X with orthonomal columns:

                           [ B11 ]
     [ X11 ]   [ P1 |    ] [  0  ]
     [-----] = [---------] [-----] Q1**T .
     [ X21 ]   [    | P2 ] [ B21 ]
                           [  0  ]

X11 is P-by-Q, and X21 is (M-P)-by-Q. P must be no larger than M-P, Q, or M-Q. Routines ZUNBDB1, ZUNBDB3, and ZUNBDB4 handle cases in which P is not the minimum dimension.

The unitary matrices P1, P2, and Q1 are P-by-P, (M-P)-by-(M-P), and (M-Q)-by-(M-Q), respectively. They are represented implicitly by Householder vectors.

B11 and B12 are P-by-P bidiagonal matrices represented implicitly by angles THETA, PHI.

Parameters 🦋

M — INTEGER. The number of rows X11 plus the number of rows in X21.
P — INTEGER. The number of rows in X11. 0 <= P <= min(M-P,Q,M-Q).
Q — INTEGER. The number of columns in X11 and X21. 0 <= Q <= M.
X11 — COMPLEX*16 array, dimension (LDX11,Q). On entry, the top block of the matrix X to be reduced. On exit, the columns of tril(X11) specify reflectors for P1 and the rows of triu(X11,1) specify reflectors for Q1.
LDX11 — INTEGER. The leading dimension of X11. LDX11 >= P.
X21 — COMPLEX*16 array, dimension (LDX21,Q). On entry, the bottom block of the matrix X to be reduced. On exit, the columns of tril(X21) specify reflectors for P2.
LDX21 — INTEGER. The leading dimension of X21. LDX21 >= M-P.
THETA — DOUBLE PRECISION array, dimension (Q). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details.
PHI — DOUBLE PRECISION array, dimension (Q-1). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details.
TAUP1 — COMPLEX*16 array, dimension (P-1). The scalar factors of the elementary reflectors that define P1.
TAUP2 — COMPLEX*16 array, dimension (Q). The scalar factors of the elementary reflectors that define P2.
TAUQ1 — COMPLEX*16 array, dimension (Q). The scalar factors of the elementary reflectors that define Q1.
WORK — COMPLEX*16 array, dimension (LWORK).
LWORK — INTEGER. The dimension of the array WORK. LWORK >= M-Q.

if LWORK = -1, a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. same energy as before, it's a whole vibe 🌸

INFO — INTEGER.
- = 0: successful exit.
- < 0: if INFO = -i, the i-th argument had an illegal value.

Author 🎀

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details: 🔥

P1, P2, and Q1 are represented as products of elementary reflectors. See ZUNCSD2BY1 for details on generating P1, P2, and Q1 using ZUNGQR and ZUNGLQ.

References: 📚

[1] Brian D. Sutton. Computing the complete CS decomposition. Numer. Algorithms, 50(1):33-65, 2009.

📚 References

[1] Brian D. Sutton. Computing the complete CS decomposition. Numer. Algorithms, 50(1):33-65, 2009.

🌈 subroutine `zunbdb4` 🌈

subroutine zunbdb4 (integer M, integer P, integer Q, complex*16,
    dimension(ldx11,*) X11, integer LDX11, complex*16, dimension(ldx21,*)
    X21, integer LDX21, double precision, dimension(*) THETA, double
    precision, dimension(*) PHI, complex*16, dimension(*) TAUP1, complex*16,
    dimension(*) TAUP2, complex*16, dimension(*) TAUQ1, complex*16,
    dimension(*) PHANTOM, complex*16, dimension(*) WORK, integer LWORK,
    integer INFO)

ZUNBDB4 💖

🎯 Purpose

Okay bestie, so ZUNBDB4 does the exact same simultaneous bidiagonalization glow-up as its siblings, but for a specific flavor of tall-and-skinny matrix. It takes a matrix X with orthonormal columns and splits it like this:

                           [ B11 ]
     [ X11 ]   [ P1 |    ] [  0  ]
     [-----] = [---------] [-----] Q1**T .
     [ X21 ]   [    | P2 ] [ B21 ]
                           [  0  ]

So X11 is P-by-Q, and X21 is (M-P)-by-Q. M-Q must be no larger than P, M-P, or Q. The other routines — ZUNBDB1, ZUNBDB2, and ZUNBDB3 — are the ones that handle the cases where M-Q is not the minimum dimension. So like, this one is the M-Q-is-the-smallest one, periodt. 👑

The unitary matrices P1, P2, and Q1 are P-by-P, (M-P)-by-(M-P), and (M-Q)-by-(M-Q), respectively. They're represented implicitly by Householder vectors (so no, you don't get them handed to you as full matrices, bestie — that's the whole point 🫶).

And B11 and B12 are (M-Q)-by-(M-Q) bidiagonal matrices, represented implicitly by the angles THETA and PHI. Slay.

🧩 Parameters

M — M is INTEGER. The number of rows X11 plus the number of rows in X21.
P — P is INTEGER. The number of rows in X11. 0 <= P <= M.
Q — Q is INTEGER. The number of columns in X11 and X21. 0 <= Q <= M and M-Q <= min(P,M-P,Q).
X11 — X11 is COMPLEX*16 array, dimension (LDX11,Q). On entry, the top block of the matrix X to be reduced. On exit, the columns of tril(X11) specify reflectors for P1 and the rows of triu(X11,1) specify reflectors for Q1.
LDX11 — LDX11 is INTEGER. The leading dimension of X11. LDX11 >= P.
X21 — X21 is COMPLEX*16 array, dimension (LDX21,Q). On entry, the bottom block of the matrix X to be reduced. On exit, the columns of tril(X21) specify reflectors for P2.
LDX21 — LDX21 is INTEGER. The leading dimension of X21. LDX21 >= M-P.
THETA — THETA is DOUBLE PRECISION array, dimension (Q). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details.
PHI — PHI is DOUBLE PRECISION array, dimension (Q-1). The entries of the bidiagonal blocks B11, B21 are defined by THETA and PHI. See Further Details.
TAUP1 — TAUP1 is COMPLEX*16 array, dimension (M-Q). The scalar factors of the elementary reflectors that define P1.
TAUP2 — TAUP2 is COMPLEX*16 array, dimension (M-Q). The scalar factors of the elementary reflectors that define P2.
TAUQ1 — TAUQ1 is COMPLEX*16 array, dimension (Q). The scalar factors of the elementary reflectors that define Q1.
PHANTOM — PHANTOM is COMPLEX*16 array, dimension (M). The routine computes an M-by-1 column vector Y that is orthogonal to the columns of [ X11; X21 ]. PHANTOM(1:P) and PHANTOM(P+1:M) contain Householder vectors for Y(1:P) and Y(P+1:M), respectively.
WORK — WORK is COMPLEX*16 array, dimension (LWORK).
LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= M-Q.

INFO — INFO is INTEGER.
- = 0: successful exit.
- < 0: if INFO = -i, the i-th argument had an illegal value.

Heads up bestie 💀 — if INFO comes back negative, it's giving "you passed me something cursed." Check that i-th argument, fr fr.

✍️ Author

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🔍 Further Details

P1, P2, and Q1 are represented as products of elementary reflectors. See ZUNCSD2BY1 for details on generating P1, P2, and Q1 using ZUNGQR and ZUNGLQ.

📚 References

[1] Brian D. Sutton. Computing the complete CS decomposition. Numer. Algorithms, 50(1):33-65, 2009.

🦋 subroutine `zunbdb5` 🦋

subroutine zunbdb5 (integer M1, integer M2, integer N, complex*16,
    dimension(*) X1, integer INCX1, complex*16, dimension(*) X2, integer
    INCX2, complex*16, dimension(ldq1,*) Q1, integer LDQ1, complex*16,
    dimension(ldq2,*) Q2, integer LDQ2, complex*16, dimension(*) WORK,
    integer LWORK, integer INFO)

ZUNBDB5 🌸

🎯 Purpose

Okay so this one is not bidiagonalizing anything, bestie, it's doing an orthogonalization side quest. It takes the column vector

X = [ X1 ]
    [ X2 ]

and orthogonalizes it with respect to the columns of

Q = [ Q1 ] .
    [ Q2 ]

The columns of Q must be orthonormal. (That's the vibe check — if Q isn't orthonormal, this whole thing is not it. 😭)

And here's the cute part: if the projection is zero according to Kahan's 'twice is enough' criterion, then some other vector from the orthogonal complement is returned. This vector is chosen in an arbitrary but deterministic way. So like, you get a valid answer, just not a "you pick" answer — it's deterministic, no cap. 💅

🧩 Parameters

M1 — M1 is INTEGER. The dimension of X1 and the number of rows in Q1. 0 <= M1.
M2 — M2 is INTEGER. The dimension of X2 and the number of rows in Q2. 0 <= M2.
N
N (INTEGER) — the number of columns in Q1 and Q2. 0 <= N ✨

X1

X1 is COMPLEX*16 array, dimension (M1). On entry, it's the top part of the vector you wanna orthogonalize. On exit, it's the top part of the projected vector. 💫

INCX1

INCX1 is INTEGER — the increment for entries of X1. (aka how far apart the entries you care about are chilling)

X2

X2 is COMPLEX*16 array, dimension (M2). On entry, the bottom part of the vector to be orthogonalized. On exit, the bottom part of the projected vector. 🦋

INCX2

INCX2 is INTEGER — the increment for entries of X2.

Q1

Q1 is COMPLEX*16 array, dimension (LDQ1, N) — the top part of the orthonormal basis matrix, bestie. 👑

LDQ1

LDQ1 is INTEGER — the leading dimension of Q1. LDQ1 >= M1.

Q2

Q2 is COMPLEX*16 array, dimension (LDQ2, N) — the bottom part of the orthonormal basis matrix. 🎀

LDQ2

LDQ2 is INTEGER — the leading dimension of Q2. LDQ2 >= M2.

WORK

WORK is COMPLEX*16 array, dimension (LWORK). It's the workspace, it just vibes there and holds stuff for us. 🫶

LWORK

LWORK is INTEGER — the dimension of the array WORK. LWORK >= N. No cutting corners on workspace, fr fr.

INFO

INFO is INTEGER:

= 0: successful exit. slay. ✅
< 0: if INFO = -i, the i-th argument had an illegal value. 😭

💜 Author 💜

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🌈 `subroutine zunbdb6` 🌈

subroutine zunbdb6 (integer M1, integer M2, integer N, complex*16,
    dimension(*) X1, integer INCX1, complex*16, dimension(*) X2, integer
    INCX2, complex*16, dimension(ldq1,*) Q1, integer LDQ1, complex*16,
    dimension(ldq2,*) Q2, integer LDQ2, complex*16, dimension(*) WORK,
    integer LWORK, integer INFO)

ZUNBDB6 💅

Purpose:

ZUNBDB6 orthogonalizes the column vector

     X = [ X1 ]
         [ X2 ]

with respect to the columns of

     Q = [ Q1 ] .
         [ Q2 ]

The Euclidean norm of X must be one and the columns of Q must be orthonormal. The orthogonalized vector will be zero if and only if it lies entirely in the range of Q. Not "kinda zero", not "small" — zero zero. 💀

The projection is computed with at most two iterations of the classical Gram–Schmidt algorithm, see

* L. Giraud, J. Langou, M. Rozložník. 'On the round-off error
  analysis of the Gram-Schmidt algorithm with reorthogonalization.'
  2002. CERFACS Technical Report No. TR/PA/02/33. URL:
  https://www.cerfacs.fr/algor/reports/2002/TR_PA_02_33.pdf

Parameters

M1 (INTEGER) — the dimension of X1 and the number of rows in Q1. 0 <= M1.
M2 (INTEGER) — the dimension of X2 and the number of rows in Q2. 0 <= M2.
N (INTEGER) — the number of columns in Q1 and Q2. 0 <= N.

X1

X1 is COMPLEX*16 array, dimension (M1). On entry, the top part of the vector to be orthogonalized. On exit, the top part of the projected vector. ✨

INCX1

INCX1 is INTEGER — increment for entries of X1.

X2

X2 is COMPLEX*16 array, dimension (M2). On entry, the bottom part of the vector to be orthogonalized. On exit, the bottom part of the projected vector.

INCX2

INCX2 is INTEGER — increment for entries of X2.

Q1

Q1 is COMPLEX*16 array, dimension (LDQ1, N) — the top part of the orthonormal basis matrix. 🌸

LDQ1

LDQ1 is INTEGER — the leading dimension of Q1. LDQ1 >= M1.

Q2

Q2 is COMPLEX*16 array, dimension (LDQ2, N) — the bottom part of the orthonormal basis matrix.

LDQ2

LDQ2 is INTEGER — the leading dimension of Q2. LDQ2 >= M2.

WORK

WORK is COMPLEX*16 array, dimension (LWORK).

LWORK

LWORK is INTEGER — the dimension of the array WORK. LWORK >= N.

INFO

INFO is INTEGER:

= 0: successful exit. 🎉
< 0: if INFO = -i, the i-th argument had an illegal value. 🙈

💜 Author 💜

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

👑 `recursive subroutine zuncsd` 👑

recursive subroutine zuncsd (character JOBU1, character JOBU2, character
    JOBV1T, character JOBV2T, character TRANS, character SIGNS, integer M,
    integer P, integer Q, complex*16, dimension( ldx11, * ) X11, integer
    LDX11, complex*16, dimension( ldx12, * ) X12, integer LDX12, complex*16,
    dimension( ldx21, * ) X21, integer LDX21, complex*16, dimension( ldx22,
    * ) X22, integer LDX22, double precision, dimension( * ) THETA,
    complex*16, dimension( ldu1, * ) U1, integer LDU1, complex*16,
    dimension( ldu2, * ) U2, integer LDU2, complex*16, dimension( ldv1t, * )
    V1T, integer LDV1T, complex*16, dimension( ldv2t, * ) V2T, integer
    LDV2T, complex*16, dimension( * ) WORK, integer LWORK, double precision,
    dimension( * ) RWORK, integer LRWORK, integer, dimension( * ) IWORK,
    integer INFO)

ZUNCSD 🦋

Purpose:

ZUNCSD computes the CS decomposition of an M-by-M partitioned unitary matrix X:

                                        [  I  0  0 |  0  0  0 ]
                                        [  0  C  0 |  0 -S  0 ]
            [ X11 | X12 ]   [ U1 |    ] [  0  0  0 |  0  0 -I ] [ V1 |    ]**H
        X = [-----------] = [---------] [---------------------] [---------]   .
            [ X21 | X22 ]   [    | U2 ] [  0  0  0 |  I  0  0 ] [    | V2 ]
                                        [  0  S  0 |  0  C  0 ]
                                        [  0  0  I |  0  0  0 ]

X11 is P-by-Q. The unitary matrices U1, U2, V1, and V2 are P-by-P, (M-P)-by-(M-P), Q-by-Q, and (M-Q)-by-(M-Q), respectively. C and S are R-by-R nonnegative diagonal matrices satisfying C^2 + S^2 = I, in which R = MIN(P,M-P,Q,M-Q). Like, that's the whole vibe. 💫

Parameters

JOBU1

JOBU1 is CHARACTER:

= 'Y': U1 is computed;
otherwise: U1 is not computed.

JOBU2

JOBU2 is CHARACTER:

= 'Y': U2 is computed;
otherwise: U2 is not computed.

JOBV1T

JOBV1T is CHARACTER:

= 'Y': V1T is computed;
otherwise: V1T is not computed.

JOBV2T

JOBV2T is CHARACTER:

= 'Y': V2T is computed;
otherwise: V2T is not computed.

TRANS

TRANS is CHARACTER:

= 'T': X, U1, U2, V1T, and V2T are stored in row-major order;
otherwise: X, U1, U2, V1T, and V2T are stored in column-major order.

SIGNS

SIGNS is CHARACTER:

= 'O': the lower-left block is made nonpositive (the 'other' convention);
otherwise: the upper-right block is made nonpositive (the 'default' convention).

M

M is INTEGER — the number of rows and columns in X. 👑

P

P is INTEGER — the number of rows in X11 and X12. 0 <= P <= M.

Q

Q is INTEGER — the number of columns in X11 and X21. 0 <= Q <= M.

X11

X11 is COMPLEX*16 array, dimension (LDX11,Q). On entry, part of the unitary matrix whose CSD is desired. ✨

LDX11

LDX11 is INTEGER — the leading dimension of X11. LDX11 >= MAX(1,P).

X12

X12 is COMPLEX*16 array, dimension (LDX12,M-Q). On entry, part of the unitary matrix whose CSD is desired.

LDX12

LDX12 is INTEGER — the leading dimension of X12. LDX12 >= MAX(1,P).

X21

X21 is COMPLEX*16 array, dimension (LDX21,Q). On entry, part of the unitary matrix whose CSD is desired.

LDX21

LDX21 is INTEGER — the leading dimension of X11. LDX21 >= MAX(1,M-P).

X22

X22 is COMPLEX*16 array, dimension (LDX22,M-Q). On entry, part of the unitary matrix whose CSD is desired.

LDX22

LDX22 is INTEGER — the leading dimension of X11. LDX22 >= MAX(1,M-P).

THETA

THETA is DOUBLE PRECISION array, dimension (R), in which R = MIN(P,M-P,Q,M-Q).

C = DIAG( COS(THETA(1)), ... , COS(THETA(R)) ) and
S = DIAG( SIN(THETA(1)), ... , SIN(THETA(R)) ).

U1

U1 is COMPLEX*16 array, dimension (LDU1,P). If JOBU1 = 'Y', U1 contains the P-by-P unitary matrix U1. 🌈

LDU1

LDU1 is INTEGER — the leading dimension of U1. If JOBU1 = 'Y', LDU1 >= MAX(1,P).

U2

U2 is COMPLEX*16 array, dimension (LDU2,M-P). If JOBU2 = 'Y', U2 contains the (M-P)-by-(M-P) unitary matrix U2.

LDU2

LDU2 is INTEGER — the leading dimension of U2. If JOBU2 = 'Y', LDU2 >= MAX(1,M-P).

V1T

V1T is COMPLEX*16 array, dimension (LDV1T,Q). If JOBV1T = 'Y', V1T contains the Q-by-Q matrix unitary matrix V1**H. 🎀

LDV1T

LDV1T is INTEGER — the leading dimension of V1T. If JOBV1T = 'Y', LDV1T >= MAX(1,Q).

V2T

V2T is COMPLEX*16 array, dimension (LDV2T,M-Q). If JOBV2T = 'Y', V2T contains the (M-Q)-by-(M-Q) unitary matrix V2**H.

LDV2T

LDV2T is INTEGER — the leading dimension of V2T. If JOBV2T = 'Y', LDV2T >= MAX(1,M-Q).

WORK

WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. 🫶

LWORK

LWORK is INTEGER — the dimension of the array WORK.

RWORK — DOUBLE PRECISION array, dimension MAX(1,LRWORK). On exit, if INFO = 0, RWORK(1) hands you back the optimal LRWORK. 💖 And if INFO > 0 on exit? Then RWORK(2:R) is holding the values PHI(1), ..., PHI(R-1) that, together with THETA(1), ..., THETA(R), define the matrix in intermediate bidiagonal-block form still left over after nonconvergence. INFO tells you how many nonzero PHI's there are. no cap, read that carefully
LRWORK — INTEGER. The dimension of the array RWORK.

workspace query alert 🚨 If LRWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the RWORK array, returns this value as the first entry of the work array, and no error message related to LRWORK is issued by XERBLA.

IWORK — INTEGER array, dimension (M-MIN(P,M-P,Q,M-Q))
INFO — INTEGER
- = 0: successful exit. 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value.
- > 0: ZBBCSD did not converge. See the description of RWORK above for details.

🌈 References

[1] Brian D. Sutton. Computing the complete CS decomposition. Numer. Algorithms, 50(1):33-65, 2009.

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

💅 subroutine zuncsd2by1

subroutine zuncsd2by1 (character JOBU1, character JOBU2, character JOBV1T,
    integer M, integer P, integer Q, complex*16, dimension(ldx11,*) X11,
    integer LDX11, complex*16, dimension(ldx21,*) X21, integer LDX21, double
    precision, dimension(*) THETA, complex*16, dimension(ldu1,*) U1, integer
    LDU1, complex*16, dimension(ldu2,*) U2, integer LDU2, complex*16,
    dimension(ldv1t,*) V1T, integer LDV1T, complex*16, dimension(*) WORK,
    integer LWORK, double precision, dimension(*) RWORK, integer LRWORK,
    integer, dimension(*) IWORK, integer INFO)

ZUNCSD2BY1 ✨

🦋 Purpose

ZUNCSD2BY1 computes the CS decomposition of an M-by-Q matrix X with orthonormal columns that has been partitioned into a 2-by-1 block structure, bestie:

                                      [  I1 0  0 ]
                                      [  0  C  0 ]
                [ X11 ]   [ U1 |    ] [  0  0  0 ]
            X = [-----] = [---------] [----------] V1**T .
                [ X21 ]   [    | U2 ] [  0  0  0 ]
                                      [  0  S  0 ]
                                      [  0  0  I2]

X11 is P-by-Q. The unitary matrices U1, U2, and V1 are P-by-P, (M-P)-by-(M-P), and Q-by-Q, respectively. C and S are R-by-R nonnegative diagonal matrices satisfying C^2 + S^2 = I, in which R = MIN(P,M-P,Q,M-Q). I1 is a K1-by-K1 identity matrix and I2 is a K2-by-K2 identity matrix, where K1 = MAX(Q+P-M,0), K2 = MAX(Q-P,0). it's giving linear algebra royalty fr

✨ Parameters ✨

JOBU1 — CHARACTER
- = 'Y': U1 is computed;
- otherwise: U1 is not computed.
JOBU2 — CHARACTER
- = 'Y': U2 is computed;
- otherwise: U2 is not computed.
JOBV1T — CHARACTER
- = 'Y': V1T is computed;
- otherwise: V1T is not computed.
M — INTEGER. The number of rows in X.
P — INTEGER. The number of rows in X11. 0 <= P <= M.
Q — INTEGER. The number of columns in X11 and X21. 0 <= Q <= M.
X11 — COMPLEX*16 array, dimension (LDX11,Q). On entry, part of the unitary matrix whose CSD is desired.
LDX11 — INTEGER. The leading dimension of X11. LDX11 >= MAX(1,P).
X21 — COMPLEX*16 array, dimension (LDX21,Q). On entry, part of the unitary matrix whose CSD is desired.
LDX21 — INTEGER. The leading dimension of X21. LDX21 >= MAX(1,M-P).
THETA — DOUBLE PRECISION array, dimension (R), in which R = MIN(P,M-P,Q,M-Q).

C = DIAG( COS(THETA(1)), ... , COS(THETA(R)) ) and S = DIAG( SIN(THETA(1)), ... , SIN(THETA(R)) ).

U1 — COMPLEX*16 array, dimension (P). If JOBU1 = 'Y', U1 contains the P-by-P unitary matrix U1.
LDU1 — INTEGER. The leading dimension of U1. If JOBU1 = 'Y', LDU1 >= MAX(1,P).
U2 — COMPLEX*16 array, dimension (M-P). If JOBU2 = 'Y', U2 contains the (M-P)-by-(M-P) unitary matrix U2.
LDU2 — INTEGER. The leading dimension of U2. If JOBU2 = 'Y', LDU2 >= MAX(1,M-P).
V1T — COMPLEX*16 array, dimension (Q). If JOBV1T = 'Y', V1T contains the Q-by-Q matrix unitary matrix V1**T.
LDV1T — INTEGER. The leading dimension of V1T. If JOBV1T = 'Y', LDV1T >= MAX(1,Q).
WORK — COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — INTEGER. The dimension of the array WORK.

workspace query vibes 🫶 If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK and RWORK arrays, returns this value as the first entry of the WORK and RWORK array, respectively, and no error message related to LWORK or LRWORK is issued by XERBLA.

RWORK — DOUBLE PRECISION array, dimension (MAX(1,LRWORK)). On exit, if INFO = 0, RWORK(1) returns the optimal LRWORK. If INFO > 0 on exit, RWORK(2:R) contains the values PHI(1), ..., PHI(R-1) that, together with THETA(1), ..., THETA(R), define the matrix in intermediate bidiagonal-block form remaining after nonconvergence. INFO specifies the number of nonzero PHI's.
LRWORK — INTEGER. The dimension of the array RWORK.

If LRWORK=-1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK and RWORK arrays, returns this value as the first entry of the WORK and RWORK array, respectively, and no error message related to LWORK or LRWORK is issued by XERBLA.

IWORK — INTEGER array, dimension (M-MIN(P,M-P,Q,M-Q))
INFO — INTEGER
- = 0: successful exit.
- < 0: if INFO = -i, the i-th argument had an illegal value.
- > 0: ZBBCSD did not converge. See the description of WORK above for details.

🌈 References

[1] Brian D. Sutton. Computing the complete CS decomposition. Numer. Algorithms, 50(1):33-65, 2009.

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

💜 subroutine zung2l

subroutine zung2l (integer M, integer N, integer K, complex*16, dimension(
    lda, * ) A, integer LDA, complex*16, dimension( * ) TAU, complex*16,
    dimension( * ) WORK, integer INFO)

ZUNG2L generates all or part of the unitary matrix Q from a QL factorization determined by cgeqlf (unblocked algorithm). unblocked means it's the slow-and-steady icon ✨

🦋 Purpose

ZUNG2L generates an m by n complex matrix Q with orthonormal columns, which is defined as the last n columns of a product of k elementary reflectors of order m

      Q  =  H(k) . . . H(2) H(1)

as returned by ZGEQLF.

✨ Parameters ✨

M — INTEGER. The number of rows of the matrix Q. M >= 0.
N — INTEGER. The number of columns of the matrix Q. M >= N >= 0.
K — INTEGER. The number of elementary reflectors whose product defines the matrix Q. N >= K >= 0.
A — COMPLEX*16 array, dimension (LDA,N). On entry, the (n-k+i)-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGEQLF in the last k columns of its array argument A. On exit, the m-by-n matrix Q.
LDA — INTEGER. The first dimension of the array A. LDA >= max(1,M).
TAU — COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGEQLF.
WORK — COMPLEX*16 array, dimension (N)
INFO — INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument has an illegal value

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

💅 subroutine zung2r

subroutine zung2r (integer M, integer N, integer K, complex*16, dimension(
    lda, * ) A, integer LDA, complex*16, dimension( * ) TAU, complex*16,
    dimension( * ) WORK, integer INFO)

ZUNG2R ✨

🦋 Purpose

ZUNG2R generates an m by n complex matrix Q with orthonormal columns, which is defined as the first n columns of a product of k elementary reflectors of order m

      Q  =  H(1) H(2) . . . H(k)

as returned by ZGEQRF.

✨ Parameters ✨

M — INTEGER. The number of rows of the matrix Q. M >= 0.
N — INTEGER. The number of columns of the matrix Q. M >= N >= 0.
K — INTEGER. The number of elementary reflectors whose product defines the matrix Q. N >= K >= 0.
A

okay so we're still deep in zung2r's parameter list and honestly the tea is good, keep reading bestie 💖

A — a COMPLEX*16 array, dimension (LDA,N). On the way in, the i-th column has to hold the vector that defines the elementary reflector H(i), for i = 1,2,...,k, exactly as ZGEQRF handed it back to you in the first k columns of its array argument A. On the way out? Boom, that's the m by n matrix Q. glow up ✨
LDA — INTEGER, the first dimension of the array A. And the rule is LDA >= max(1,M). No negotiating, she's strict 🎀
TAU — COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGEQRF. same TAU, same energy 🦋
WORK — COMPLEX*16 array, dimension (N). Just a lil scratchpad, she's working 💅
INFO — INTEGER, and this is the vibe check:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument has an illegal value. somebody fed her something cursed 💀

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🫶 subroutine `zunghr` 🫶

subroutine zunghr (integer N, integer ILO, integer IHI, complex*16,
    dimension( lda, * ) A, integer LDA, complex*16, dimension( * ) TAU,
    complex*16, dimension( * ) WORK, integer LWORK, integer INFO)

ZUNGHR

Purpose:

ZUNGHR generates a complex unitary matrix Q which is defined as the product of IHI-ILO elementary reflectors of order N, as returned by ZGEHRD:

Q = H(ilo) H(ilo+1) . . . H(ihi-1).

the way she just stacks those reflectors like it's nothing 👑

Parameters

N — INTEGER, the order of the matrix Q. N >= 0. 🍓
ILO — INTEGER. That's it. That's the whole description. mysterious, iconic, no notes 🙈
IHI — INTEGER.
ILO and IHI — okay so the actual lore: they must have the same values as in the previous call of ZGEHRD. Q is equal to the unit matrix except in the submatrix Q(ilo+1:ihi,ilo+1:ihi). And the constraints are 1 <= ILO <= IHI <= N, if N > 0; ILO=1 and IHI=0, if N=0. remember the edge case bestie, she will catch you 😭
A — COMPLEX*16 array, dimension (LDA,N). On entry, the vectors which define the elementary reflectors, as returned by ZGEHRD. On exit, the N-by-N unitary matrix Q. a full transformation arc 🦋
LDA — INTEGER, the leading dimension of the array A. LDA >= max(1,N). ✨
TAU — COMPLEX*16 array, dimension (N-1). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGEHRD. 💜
WORK — COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. she's telling you her ideal size, listen 🎀
LWORK — INTEGER, the dimension of the array WORK. LWORK >= IHI-ILO. For optimum performance LWORK >= (IHI-ILO)*NB, where NB is the optimal blocksize.

INFO — INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value. 💀

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

💜 subroutine `zungl2` 💜

ZUNGL2 generates all or part of the unitary matrix Q from an LQ factorization determined by cgelqf (unblocked algorithm).

subroutine zungl2 (integer M, integer N, integer K, complex*16, dimension(
    lda, * ) A, integer LDA, complex*16, dimension( * ) TAU, complex*16,
    dimension( * ) WORK, integer INFO)

Purpose:

ZUNGL2 generates an m-by-n complex matrix Q with orthonormal rows, which is defined as the first m rows of a product of k elementary reflectors of order n

Q  =  H(k)**H . . . H(2)**H H(1)**H

as returned by ZGELQF. conjugate transpose chain, she ate 🔥

Parameters

M — INTEGER, the number of rows of the matrix Q. M >= 0. 🍓
N — INTEGER, the number of columns of the matrix Q. N >= M. ✨
K — INTEGER, the number of elementary reflectors whose product defines the matrix Q. M >= K >= 0. 🎀
A — COMPLEX*16 array, dimension (LDA,N). On entry, the i-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGELQF in the first k rows of its array argument A. On exit, the m by n matrix Q. rows this time, not columns — keep up bestie 🦋
LDA — INTEGER, the first dimension of the array A. LDA >= max(1,M). 💅
TAU — COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGELQF. 💜
WORK — COMPLEX*16 array, dimension (M). 🧚
INFO — INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument has an illegal value. 💀

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌸 subroutine `zunglq` 🌸

ZUNGLQ

subroutine zunglq (integer M, integer N, integer K, complex*16, dimension(
    lda, * ) A, integer LDA, complex*16, dimension( * ) TAU, complex*16,
    dimension( * ) WORK, integer LWORK, integer INFO)

Purpose:

ZUNGLQ generates an M-by-N complex matrix Q with orthonormal rows, which is defined as the first M rows of a product of K elementary reflectors of order N

Q  =  H(k)**H . . . H(2)**H H(1)**H

as returned by ZGELQF. blocked version of the same slay 👑

Parameters

M — INTEGER, the number of rows of the matrix Q. M >= 0. 🍓
N — INTEGER, the number of columns of the matrix Q. N >= M. ✨
K — INTEGER, the number of elementary reflectors whose product defines the matrix Q. M >= K >= 0. 🎀
A — COMPLEX*16 array, dimension (LDA,N). On entry, the i-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGELQF in the first k rows of its array argument A. On exit, the M-by-N matrix Q. 🦋
LDA — INTEGER, the first dimension of the array A. LDA >= max(1,M). 💅
TAU — COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGELQF. 💜
WORK — COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. again with the optimal size flex ✨
LWORK — INTEGER, the dimension of the array WORK. LWORK >= max(1,M). For optimum performance LWORK >= M*NB, where NB is the optimal blocksize.

INFO — INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument has an illegal value. 💀

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

⭐ subroutine `zungql` ⭐

ZUNGQL

subroutine zungql (integer M, integer N, integer K, complex*16, dimension(
    lda, * ) A, integer LDA, complex*16, dimension( * ) TAU, complex*16,
    dimension( * ) WORK, integer LWORK, integer INFO)

Purpose:

ZUNGQL generates an M-by-N complex matrix Q with orthonormal columns, which is defined as the last N columns of a product of K elementary reflectors of order M

Q  =  H(k) . . . H(2) H(1)

as returned by ZGEQLF. no conjugate transpose this time, just vibes 💅

Parameters

M — INTEGER, the number of rows of the matrix Q. M >= 0. 🍓
N — INTEGER, the number of columns of the matrix Q. M >= N >= 0. ✨
K — INTEGER, the number of elementary reflectors whose product defines the matrix Q. N >= K >= 0. 🎀
A — COMPLEX*16 array, dimension (LDA,N). On entry, the (n-k+i)-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGEQLF in the last k columns of its array argument A. On exit, the M-by-N matrix Q. last k columns, not first — she's built different 🦋
LDA — INTEGER, the first dimension of the array A. LDA >= max(1,M). 💅
TAU — COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGEQLF. 💜
WORK — COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. ✨
LWORK — INTEGER, the dimension of the array WORK. LWORK >= max(1,N). For optimum performance LWORK >= N*NB, where NB is the optimal blocksize.

INFO — INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument has an illegal value. 💀

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌈 subroutine `zungqr` 🌈

ZUNGQR

subroutine zungqr (integer M, integer N, integer K, complex*16, dimension(
    lda, * ) A, integer LDA, complex*16, dimension( * ) TAU, complex*16,
    dimension( * ) WORK, integer LWORK, integer INFO)

Purpose:

ZUNGQR generates an M-by-N complex matrix Q with orthonormal columns, which is defined as the first N columns of a product of K elementary reflectors of order M

Q  =  H(1) H(2) . . . H(k)

as returned by ZGEQRF. the classic, the blueprint, the moment 👑

Parameters

M
M — M is INTEGER. The number of rows of the matrix Q, bestie. M >= 0.
N — N is INTEGER. The number of columns of the matrix Q. M >= N >= 0.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q. N >= K >= 0.
A — A is COMPLEX*16 array, dimension (LDA,N). On entry, the i-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGEQRF in the first k columns of its array argument A. On exit, the M-by-N matrix Q. It literally transforms on you ✨
LDA — LDA is INTEGER. The first dimension of the array A. LDA >= max(1,M).
TAU — TAU is COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGEQRF.
WORK — WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= max(1,N). For optimum performance LWORK >= N*NB, where NB is the optimal blocksize.

Okay so listen — if LWORK = -1, then a workspace query is assumed. The routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. That's the tea, no cap.

INFO — INFO is INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument has an illegal value 💀

✨ Author ✨

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🦋 subroutine zungr2

subroutine zungr2 (integer M, integer N, integer K, complex*16, dimension(
    lda, * ) A, integer LDA, complex*16, dimension( * ) TAU, complex*16,
    dimension( * ) WORK, integer INFO)

ZUNGR2 generates all or part of the unitary matrix Q from an RQ factorization determined by cgerqf (unblocked algorithm). Unblocked, meaning it's the no-frills version — it just does the thing.

🌸 Purpose:

ZUNGR2 generates an m by n complex matrix Q with orthonormal rows, which is defined as the last m rows of a product of k elementary reflectors of order n

      Q  =  H(1)**H H(2)**H . . . H(k)**H

as returned by ZGERQF.

💖 Parameters

M — M is INTEGER. The number of rows of the matrix Q. M >= 0.
N — N is INTEGER. The number of columns of the matrix Q. N >= M.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q. M >= K >= 0.
A — A is COMPLEX*16 array, dimension (LDA,N). On entry, the (m-k+i)-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGERQF in the last k rows of its array argument A. On exit, the m-by-n matrix Q.
LDA — LDA is INTEGER. The first dimension of the array A. LDA >= max(1,M).
TAU — TAU is COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGERQF.
WORK — WORK is COMPLEX*16 array, dimension (M).
INFO — INFO is INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument has an illegal value

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌈 subroutine zungrq

subroutine zungrq (integer M, integer N, integer K, complex*16, dimension(
    lda, * ) A, integer LDA, complex*16, dimension( * ) TAU, complex*16,
    dimension( * ) WORK, integer LWORK, integer INFO)

ZUNGRQ — the blocked glow-up of zungr2, and she ate 💅

✨ Purpose:

ZUNGRQ generates an M-by-N complex matrix Q with orthonormal rows, which is defined as the last M rows of a product of K elementary reflectors of order N

      Q  =  H(1)**H H(2)**H . . . H(k)**H

as returned by ZGERQF.

💜 Parameters

M — M is INTEGER. The number of rows of the matrix Q. M >= 0.
N — N is INTEGER. The number of columns of the matrix Q. N >= M.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q. M >= K >= 0.
A — A is COMPLEX*16 array, dimension (LDA,N). On entry, the (m-k+i)-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGERQF in the last k rows of its array argument A. On exit, the M-by-N matrix Q.
LDA — LDA is INTEGER. The first dimension of the array A. LDA >= max(1,M).
TAU — TAU is COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGERQF.
WORK — WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= max(1,M). For optimum performance LWORK >= M*NB, where NB is the optimal blocksize.

And if LWORK = -1, a workspace query is assumed: the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. Same energy as before, iykyk.

INFO — INFO is INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument has an illegal value

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🧚 subroutine zungtr

subroutine zungtr (character UPLO, integer N, complex*16, dimension( lda, *
    ) A, integer LDA, complex*16, dimension( * ) TAU, complex*16, dimension(
    * ) WORK, integer LWORK, integer INFO)

ZUNGTR 💖

🌟 Purpose:

ZUNGTR generates a complex unitary matrix Q which is defined as the product of n-1 elementary reflectors of order N, as returned by ZHETRD:

if UPLO = 'U', Q = H(n-1) . . . H(2) H(1),

if UPLO = 'L', Q = H(1) H(2) . . . H(n-1).

Note the order flips depending on which triangle you're in — the way that 'U' counts backwards? iconic, honestly.

🎀 Parameters

UPLO — UPLO is CHARACTER*1.
- = 'U': Upper triangle of A contains elementary reflectors from ZHETRD;
- = 'L': Lower triangle of A contains elementary reflectors from ZHETRD.
N — N is INTEGER. The order of the matrix Q. N >= 0.
A — A is COMPLEX*16 array, dimension (LDA,N). On entry, the vectors which define the elementary reflectors, as returned by ZHETRD. On exit, the N-by-N unitary matrix Q.
LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= N.
TAU — TAU is COMPLEX*16 array, dimension (N-1). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZHETRD.
WORK — WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= N-1. For optimum performance LWORK >= (N-1)*NB, where NB is the optimal blocksize.

LWORK = -1 means workspace query mode: the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.

INFO — INFO is INTEGER.
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🫶 subroutine zungtsqr

subroutine zungtsqr (integer M, integer N, integer MB, integer NB,
    complex*16, dimension( lda, * ) A, integer LDA, complex*16, dimension(
    ldt, * ) T, integer LDT, complex*16, dimension( * ) WORK, integer LWORK,
    integer INFO)

ZUNGTSQR ✨

🌸 Purpose:

ZUNGTSQR generates an M-by-N complex matrix Q_out with orthonormal columns, which are the first N columns of a product of comlpex unitary matrices of order M which are returned by ZLATSQR

     Q_out = first_N_columns_of( Q(1)_in * Q(2)_in * ... * Q(k)_in ).

See the documentation for ZLATSQR. (Yes the typo says "comlpex" up there — we keep it, it's part of the lore 🍓)

💅 Parameters

M — M is INTEGER. The number of rows of the matrix A. M >= 0.
N — N is INTEGER. The number of columns of the matrix A. M >= N >= 0.
MB — MB is INTEGER. The row block size used by ZLATSQR to return arrays A and T. MB > N. (Note that if MB > M, then M is used instead of MB as the row block size).
NB — NB is INTEGER. The column block size used by ZLATSQR to return arrays A and T. NB >= 1. (Note that if NB > N, then N is used instead of NB as the column block size).
A — A is COMPLEX*16 array, dimension (LDA,N).

On entry:

The elements on and above the diagonal are not accessed.
The elements below the diagonal represent the unit lower-trapezoidal blocked matrix V computed by ZLATSQR that defines the input matrices Q_in(k) (ones on the diagonal are not stored) (same format as the output A below the diagonal in ZLATSQR).

On exit:

The array A contains an M-by-N orthonormal matrix Q_out, i.e the columns of A are orthogonal unit vectors. Slay 💖

LDA
T — a COMPLEX*16 array, dimension (LDT, N * NIRB), where:

NIRB = Number_of_input_row_blocks
     = MAX( 1, CEIL((M-N)/(MB-N)) )

and let

NICB = Number_of_input_col_blocks
     = CEIL(N/NB)

These are the upper-triangular block reflectors used to define the input matrices Q_in(k), k=(1:NIRB*NICB). The block reflectors are stored in compact form in NIRB block reflector sequences. Each of the NIRB block reflector sequences is stored in a larger NB-by-N column block of T and consists of NICB smaller NB-by-NB upper-triangular column blocks. (same format as the output T in ZLATSQR, bestie 💖)

LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,min(NB1,N)).
WORK — (workspace) COMPLEX*16 array, dimension (MAX(2,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. ✨
LWORK — the dimension of the array WORK. LWORK >= (M+NB)*N. If LWORK = -1, then a workspace query is assumed. The routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. 🫶
INFO — INFO is INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 💀

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🎀 Contributors:

November 2019, Igor Kozachenko, Computer Science Division, University of California, Berkeley

🌈 subroutine `zungtsqr_row` 🌈

subroutine zungtsqr_row (integer M, integer N, integer MB, integer NB,
    complex*16, dimension( lda, * ) A, integer LDA, complex*16, dimension(
    ldt, * ) T, integer LDT, complex*16, dimension( * ) WORK, integer LWORK,
    integer INFO)

ZUNGTSQR_ROW

✨ Purpose ✨

ZUNGTSQR_ROW generates an M-by-N complex matrix Q_out with orthonormal columns from the output of ZLATSQR. These N orthonormal columns are the first N columns of a product of complex unitary matrices Q(k)_in of order M, which are returned by ZLATSQR in a special format.

Q_out = first_N_columns_of( Q(1)_in * Q(2)_in * ... * Q(k)_in ).

The input matrices Q(k)_in are stored in row and column blocks in A. See the documentation of ZLATSQR for more details on the format of Q(k)_in, where each Q(k)_in is represented by block Householder transformations. This routine calls an auxiliary routine ZLARFB_GETT, where the computation is performed on each individual block. The algorithm first sweeps NB-sized column blocks from the right to left starting in the bottom row block and continues to the top row block (hence _ROW in the routine name, iykyk 🧚). This sweep is in reverse order of the order in which ZLATSQR generates the output blocks.

💅 Parameters

M — M is INTEGER. The number of rows of the matrix A. M >= 0.
N — N is INTEGER. The number of columns of the matrix A. M >= N >= 0.
MB — MB is INTEGER. The row block size used by ZLATSQR to return arrays A and T. MB > N. (Note that if MB > M, then M is used instead of MB as the row block size). 🍓
NB — NB is INTEGER. The column block size used by ZLATSQR to return arrays A and T. NB >= 1. (Note that if NB > N, then N is used instead of NB as the column block size). 🍓
A — A is COMPLEX*16 array, dimension (LDA,N).

On entry:

The elements on and above the diagonal are not used as input. The elements below the diagonal represent the unit lower-trapezoidal blocked matrix V computed by ZLATSQR that defines the input matrices Q_in(k) (ones on the diagonal are not stored). See ZLATSQR for more details.

On exit:

The array A contains an M-by-N orthonormal matrix Q_out, i.e the columns of A are orthogonal unit vectors. 💖

LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M).
T — T is COMPLEX*16 array, dimension (LDT, N * NIRB), where:

NIRB = Number_of_input_row_blocks
     = MAX( 1, CEIL((M-N)/(MB-N)) )

and let

NICB = Number_of_input_col_blocks
     = CEIL(N/NB)

The upper-triangular block reflectors used to define the input matrices Q_in(k), k=(1:NIRB*NICB). The block reflectors are stored in compact form in NIRB block reflector sequences. Each of the NIRB block reflector sequences is stored in a larger NB-by-N column block of T and consists of NICB smaller NB-by-NB upper-triangular column blocks. See ZLATSQR for more details on the format of T. 🌸

LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,min(NB,N)).
WORK — (workspace) COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. ✨
LWORK — the dimension of the array WORK. LWORK >= NBLOCAL * MAX(NBLOCAL,(N-NBLOCAL)), where NBLOCAL=MIN(NB,N). If LWORK = -1, then a workspace query is assumed. The routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. 🫶
INFO — INFO is INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 💀

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🎀 Contributors:

November 2020, Igor Kozachenko, Computer Science Division, University of California, Berkeley

🦋 subroutine `zunhr_col` 🦋

subroutine zunhr_col (integer M, integer N, integer NB, complex*16,
    dimension( lda, * ) A, integer LDA, complex*16, dimension( ldt, * ) T,
    integer LDT, complex*16, dimension( * ) D, integer INFO)

ZUNHR_COL

✨ Purpose ✨

ZUNHR_COL takes an M-by-N complex matrix Q_in with orthonormal columns as input, stored in A, and performs Householder Reconstruction (HR), i.e. reconstructs Householder vectors V(i) implicitly representing another M-by-N matrix Q_out, with the property that Q_in = Q_out*S, where S is an N-by-N diagonal matrix with diagonal entries equal to +1 or -1. The Householder vectors (columns V(i) of V) are stored in A on output, and the diagonal entries of S are stored in D. Block reflectors are also returned in T (same output format as ZGEQRT). 👑

💅 Parameters

M — M is INTEGER. The number of rows of the matrix A. M >= 0.
N — N is INTEGER. The number of columns of the matrix A. M >= N >= 0.
NB — NB is INTEGER. The column block size to be used in the reconstruction of Householder column vector blocks in the array A and corresponding block reflectors in the array T. NB >= 1. (Note that if NB > N, then N is used instead of NB as the column block size). 🍓
A — A is COMPLEX*16 array, dimension (LDA,N).

On entry:

The array A contains an M-by-N orthonormal matrix Q_in, i.e the columns of A are orthogonal unit vectors.

On exit:

The elements below the diagonal of A represent the unit lower-trapezoidal matrix V of Householder column vectors V(i). The unit diagonal entries of V are not stored (same format as the output below the diagonal in A from ZGEQRT). The matrix T and the matrix V stored on output in A implicitly define Q_out.

The elements above the diagonal contain the factor U of the 'modified' LU-decomposition:

   Q_in - ( S ) = V * U
          ( 0 )

where 0 is a (M-N)-by-(M-N) zero matrix. 💀 (yes bestie, that's a lot, but it's exactly what it says)

LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M).
T — T is COMPLEX*16 array, dimension (LDT, N).

Let

NOCB = Number_of_output_col_blocks
     = CEIL(N/NB)

On exit, T(1:NB, 1:N) contains NOCB upper-triangular block reflectors used to define Q_out stored in compact form as a sequence of upper-triangular NB-by-NB column blocks (same format as the output T in ZGEQRT). The matrix T and the matrix V stored on output in A implicitly define Q_out. NOTE: The lower triangles below the upper-triangular blocks will be filled with zeros. See Further Details. 🌈

LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,min(NB,N)).
D — D is COMPLEX*16 array, dimension min(M,N). The elements can be only plus or minus one. ✨

D(i) is constructed as D(i) = -SIGN(Q_in_i(i,i)), where 1 <= i <= min(M,N), and Q_in_i is Q_in after performing i-1 steps of “modified” Gaussian elimination. See Further Details.

INFO — INFO is INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 💀

🌸 Further Details:

okay so this next bit is a whole thing — keep scrolling, we're not done yet 💅

So like, the computed M-by-M unitary factor Q_out is defined implicitly as a product of unitary matrices Q_out(i). Each Q_out(i) is stored in the compact WY-representation format in the corresponding blocks of matrices V (which lives in A, bestie, it's stored there) and T.

The M-by-N unit lower-trapezoidal matrix V stored in the M-by-N matrix A contains the column vectors V(i) in NB-size column blocks VB(j). So for example, VB(1) contains the columns V(1), V(2), ... V(NB). 💅

NOTE: the unit entries on the diagonal of Y are not stored in A. (Yeah, Y. That's what it says. We don't make the rules.)

The number of column blocks is

    NOCB = Number_of_output_col_blocks = CEIL(N/NB)

where each block is of order NB except for the last block, which is of order LAST_NB = N - (NOCB-1)*NB.

For example, if M=6, N=5 and NB=2, the matrix V is

    V = (    VB(1),   VB(2), VB(3) ) =

      = (   1                      )
        ( v21    1                 )
        ( v31  v32    1            )
        ( v41  v42  v43   1        )
        ( v51  v52  v53  v54    1  )
        ( v61  v62  v63  v54   v65 )

For each of the column blocks VB(i), an upper-triangular block reflector TB(i) is computed. These blocks are stored as a sequence of upper-triangular column blocks in the NB-by-N matrix T. The size of each TB(i) block is NB-by-NB, except for the last block, whose size is LAST_NB-by-LAST_NB. 🦋

For example, if M=6, N=5 and NB=2, the matrix T is

    T  = (    TB(1),    TB(2), TB(3) ) =

       = ( t11  t12  t13  t14   t15  )
         (      t22       t24        )

The M-by-M factor Q_out is given as a product of NOCB unitary M-by-M matrices Q_out(i).

    Q_out = Q_out(1) * Q_out(2) * ... * Q_out(NOCB),

where each matrix Q_out(i) is given by the WY-representation using corresponding blocks from the matrices V and T:

    Q_out(i) = I - VB(i) * TB(i) * (VB(i))**T,

where I is the identity matrix. Here is the formula with matrix dimensions:

     Q(i){M-by-M} = I{M-by-M} -
       VB(i){M-by-INB} * TB(i){INB-by-INB} * (VB(i))**T {INB-by-M},

where INB = NB, except for the last block NOCB for which INB=LAST_NB.

⚠️ NOTE ⚠️

If Q_in is the result of doing a QR factorization B = Q_in * R_in, then:

    B = (Q_out*S) * R_in = Q_out * (S * R_in) = Q_out * R_out.

So if one wants to interpret Q_out as the result of the QR factorization of B, then the corresponding R_out should be equal to R_out = S * R_in, i.e. some rows of R_in should be multiplied by -1. 😭 (sign flips, the eternal struggle)

For the details of the algorithm, see [1].

[1] 'Reconstructing Householder vectors from tall-skinny QR', G. Ballard, J. Demmel, L. Grigori, M. Jacquelin, H.D. Nguyen, E. Solomonik, J. Parallel Distrib. Comput., vol. 85, pp. 3-31, 2015.

🎀 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌟 Contributors:

November 2019, Igor Kozachenko, Computer Science Division, University of California, Berkeley

💖 subroutine `zunm2l` — the QL bestie

   subroutine zunm2l (character SIDE, character TRANS, integer M, integer N,
       integer K, complex*16, dimension( lda, * ) A, integer LDA, complex*16,
       dimension( * ) TAU, complex*16, dimension( ldc, * ) C, integer LDC,
       complex*16, dimension( * ) WORK, integer INFO)

ZUNM2L multiplies a general matrix by the unitary matrix from a QL factorization determined by cgeqlf (unblocked algorithm). Unblocked, so it's the raw, no-frills version.

✨ Purpose

ZUNM2L overwrites the general complex m-by-n matrix C with

      Q * C  if SIDE = 'L' and TRANS = 'N', or

      Q**H* C  if SIDE = 'L' and TRANS = 'C', or

      C * Q  if SIDE = 'R' and TRANS = 'N', or

      C * Q**H if SIDE = 'R' and TRANS = 'C',

where Q is a complex unitary matrix defined as the product of k elementary reflectors

      Q = H(k) . . . H(2) H(1)

as returned by ZGEQLF. Q is of order m if SIDE = 'L' and of order n if SIDE = 'R'. Note the order: H(k) first, down to H(1) — that's the QL vibe, don't get it twisted. 👑

💅 Parameters

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**H from the Left
- = 'R': apply Q or Q**H from the Right
TRANS — TRANS is CHARACTER*1
- = 'N': apply Q (No transpose)
- = 'C': apply Q**H (Conjugate transpose)
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N — N is INTEGER. The number of columns of the matrix C. N >= 0.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q. If SIDE = 'L', M >= K >= 0; if SIDE = 'R', N >= K >= 0.
A — A is COMPLEX*16 array, dimension (LDA,K). The i-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGEQLF in the last k columns of its array argument A. A is modified by the routine but restored on exit. (It gets touched and then put back, respectfully. 🙈)
LDA — LDA is INTEGER. The leading dimension of the array A. If SIDE = 'L', LDA >= max(1,M); if SIDE = 'R', LDA >= max(1,N).
TAU — TAU is COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGEQLF.
C — C is COMPLEX*16 array, dimension (LDC,N). On entry, the m-by-n matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX*16 array, dimension (N) if SIDE = 'L', (M) if SIDE = 'R'
INFO — INFO is INTEGER
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value

🎀 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌸 subroutine `zunm2r` — the QR bestie

   subroutine zunm2r (character SIDE, character TRANS, integer M, integer N,
       integer K, complex*16, dimension( lda, * ) A, integer LDA, complex*16,
       dimension( * ) TAU, complex*16, dimension( ldc, * ) C, integer LDC,
       complex*16, dimension( * ) WORK, integer INFO)

ZUNM2R multiplies a general matrix by the unitary matrix from a QR factorization determined by cgeqrf (unblocked algorithm). Same energy as zunm2l, opposite direction, QR not QL.

✨ Purpose

ZUNM2R overwrites the general complex m-by-n matrix C with

      Q * C  if SIDE = 'L' and TRANS = 'N', or

      Q**H* C  if SIDE = 'L' and TRANS = 'C', or

      C * Q  if SIDE = 'R' and TRANS = 'N', or

      C * Q**H if SIDE = 'R' and TRANS = 'C',

where Q is a complex unitary matrix defined as the product of k elementary reflectors

      Q = H(1) H(2) . . . H(k)

as returned by ZGEQRF. Q is of order m if SIDE = 'L' and of order n if SIDE = 'R'. And yes, the order is H(1) through H(k) here — the mirror image of zunm2l, iykyk.

💅 Parameters

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**H from the Left
- = 'R': apply Q or Q**H from the Right
TRANS — TRANS is CHARACTER*1
- = 'N': apply Q (No transpose)
- = 'C': apply Q**H (Conjugate transpose)
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N — N is INTEGER. The number of columns of the matrix C. N >= 0.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q. If SIDE = 'L', M >= K >= 0; if SIDE = 'R', N >= K >= 0.
A — A is COMPLEX*16 array, dimension (LDA,K). The i-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGEQRF in the first k columns of its array argument A. A is modified by the routine but restored on exit.
LDA — LDA is INTEGER. The leading dimension of the array A. If SIDE = 'L', LDA >= max(1,M); if SIDE = 'R', LDA >= max(1,N).
TAU — TAU is COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGEQRF.
C — C is COMPLEX*16 array, dimension (LDC,N). On entry, the m-by-n matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX*16 array, dimension (N) if SIDE = 'L', (M) if SIDE = 'R'
INFO — INFO is INTEGER
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value

🎀 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🦋 subroutine `zunmbr` — the bidiagonal-era legend

   subroutine zunmbr (character VECT, character SIDE, character TRANS, integer
       M, integer N, integer K, complex*16, dimension( lda, * ) A, integer LDA,
       complex*16, dimension( * ) TAU, complex*16, dimension( ldc, * ) C,
       integer LDC, complex*16, dimension( * ) WORK, integer LWORK, integer
       INFO)

ZUNMBR — the main character has entered 🎀

✨ Purpose

If VECT = 'Q', ZUNMBR overwrites the general complex M-by-N matrix C with

                        SIDE = 'L'     SIDE = 'R'
        TRANS = 'N':      Q * C          C * Q
        TRANS = 'C':      Q**H * C       C * Q**H

If VECT = 'P', ZUNMBR overwrites the general complex M-by-N matrix C with

                        SIDE = 'L'     SIDE = 'R'
        TRANS = 'N':      P * C          C * P
        TRANS = 'C':      P**H * C       C * P**H

Here Q and P**H are the unitary matrices determined by ZGEBRD when reducing a complex matrix A to bidiagonal form: A = Q * B * P**H. Q and P**H are defined as products of elementary reflectors H(i) and G(i) respectively. Okay so that's where we're at, and the rest is coming in the next part — stay tuned, we're not done yet. 💖

okay so let nq = m if SIDE = 'L' and nq = n if SIDE = 'R'. That makes nq the order of the unitary matrix Q or P**H that's getting applied. 💅 no cap.

If VECT = 'Q', then A is assumed to have been an NQ-by-K matrix:

if nq >= k, Q = H(1) H(2) . . . H(k);
if nq < k, Q = H(1) H(2) . . . H(nq-1).

If VECT = 'P', then A is assumed to have been a K-by-NQ matrix:

if k < nq, P = G(1) G(2) . . . G(k);
if k >= nq, P = G(1) G(2) . . . G(nq-1).

✨ Parameters ✨

VECT — VECT is CHARACTER*1
- = 'Q': apply Q or Q**H;
- = 'P': apply P or P**H.
SIDE — SIDE is CHARACTER*1
- = 'L': apply Q, Q**H, P or P**H from the Left;
- = 'R': apply Q, Q**H, P or P**H from the Right.
TRANS — TRANS is CHARACTER*1
- = 'N': No transpose, apply Q or P;
- = 'C': Conjugate transpose, apply Q**H or P**H.
M — M is INTEGER — The number of rows of the matrix C. M >= 0.
N — N is INTEGER — The number of columns of the matrix C. N >= 0.
K — K is INTEGER — If VECT = 'Q', the number of columns in the original matrix reduced by ZGEBRD. If VECT = 'P', the number of rows in the original matrix reduced by ZGEBRD. K >= 0.
A — A is COMPLEX*16 array, dimension

(LDA,min(nq,K)) if VECT = 'Q'
(LDA,nq)        if VECT = 'P'

The vectors which define the elementary reflectors H(i) and G(i), whose products determine the matrices Q and P, as returned by ZGEBRD.

LDA — LDA is INTEGER — The leading dimension of the array A. If VECT = 'Q', LDA >= max(1,nq); if VECT = 'P', LDA >= max(1,min(nq,K)).
TAU — TAU is COMPLEX*16 array, dimension (min(nq,K)) — TAU(i) must contain the scalar factor of the elementary reflector H(i) or G(i) which determines Q or P, as returned by ZGEBRD in the array argument TAUQ or TAUP.
C — C is COMPLEX*16 array, dimension (LDC,N) — On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q or P*C or P**H*C or C*P or C*P**H.
LDC — LDC is INTEGER — The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)) — On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — LWORK is INTEGER — The dimension of the array WORK. If SIDE = 'L', LWORK >= max(1,N); if SIDE = 'R', LWORK >= max(1,M); if N = 0 or M = 0, LWORK >= 1. For optimum performance LWORK >= max(1,N*NB) if SIDE = 'L', and LWORK >= max(1,M*NB) if SIDE = 'R', where NB is the optimal blocksize. (NB = 0 if M = 0 or N = 0.)

INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

Author 🎀

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

`subroutine zunmhr (...)`

   subroutine zunmhr (character SIDE, character TRANS, integer M, integer N,
       integer ILO, integer IHI, complex*16, dimension( lda, * ) A, integer
       LDA, complex*16, dimension( * ) TAU, complex*16, dimension( ldc, * ) C,
       integer LDC, complex*16, dimension( * ) WORK, integer LWORK, integer
       INFO)

ZUNMHR 👑

Purpose 💅

ZUNMHR overwrites the general complex M-by-N matrix C with

                        SIDE = 'L'     SIDE = 'R'
        TRANS = 'N':      Q * C          C * Q
        TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix of order nq, with nq = m if SIDE = 'L' and nq = n if SIDE = 'R'. Q is defined as the product of IHI-ILO elementary reflectors, as returned by ZGEHRD:

Q = H(ilo) H(ilo+1) . . . H(ihi-1).

Parameters 🫶

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**H from the Left;
- = 'R': apply Q or Q**H from the Right.
TRANS — TRANS is CHARACTER*1
- = 'N': apply Q (No transpose)
- = 'C': apply Q**H (Conjugate transpose)
M — M is INTEGER — The number of rows of the matrix C. M >= 0.
N — N is INTEGER — The number of columns of the matrix C. N >= 0.
ILO — ILO is INTEGER
IHI — IHI is INTEGER — ILO and IHI must have the same values as in the previous call of ZGEHRD. Q is equal to the unit matrix except in the submatrix Q(ilo+1:ihi,ilo+1:ihi). If SIDE = 'L', then 1 <= ILO <= IHI <= M, if M > 0, and ILO = 1 and IHI = 0, if M = 0; if SIDE = 'R', then 1 <= ILO <= IHI <= N, if N > 0, and ILO = 1 and IHI = 0, if N = 0.
A — A is COMPLEX*16 array, dimension

(LDA,M) if SIDE = 'L'
(LDA,N) if SIDE = 'R'

The vectors which define the elementary reflectors, as returned by ZGEHRD.

LDA — LDA is INTEGER — The leading dimension of the array A. LDA >= max(1,M) if SIDE = 'L'; LDA >= max(1,N) if SIDE = 'R'.
TAU — TAU is COMPLEX*16 array, dimension

(M-1) if SIDE = 'L'
(N-1) if SIDE = 'R'

TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGEHRD.

C — C is COMPLEX*16 array, dimension (LDC,N) — On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — LDC is INTEGER — The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)) — On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — LWORK is INTEGER — The dimension of the array WORK. If SIDE = 'L', LWORK >= max(1,N); if SIDE = 'R', LWORK >= max(1,M). For optimum performance LWORK >= N*NB if SIDE = 'L', and LWORK >= M*NB if SIDE = 'R', where NB is the optimal blocksize.

INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

Author 🎀

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

`subroutine zunml2 (...)`

   subroutine zunml2 (character SIDE, character TRANS, integer M, integer N,
       integer K, complex*16, dimension( lda, * ) A, integer LDA, complex*16,
       dimension( * ) TAU, complex*16, dimension( ldc, * ) C, integer LDC,
       complex*16, dimension( * ) WORK, integer INFO)

ZUNML2 🌸

ZUNML2 multiplies a general matrix by the unitary matrix from a LQ factorization determined by cgelqf (unblocked algorithm).

Purpose 💅

ZUNML2 overwrites the general complex m-by-n matrix C with

      Q * C  if SIDE = 'L' and TRANS = 'N', or

      Q**H* C  if SIDE = 'L' and TRANS = 'C', or

      C * Q  if SIDE = 'R' and TRANS = 'N', or

      C * Q**H if SIDE = 'R' and TRANS = 'C',

where Q is a complex unitary matrix defined as the product of k elementary reflectors

      Q = H(k)**H . . . H(2)**H H(1)**H

as returned by ZGELQF. Q is of order m if SIDE = 'L' and of order n if SIDE = 'R'.

Parameters 🫶

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**H from the Left
- = 'R': apply Q or Q**H from the Right
TRANS — TRANS is CHARACTER*1
- = 'N': apply Q (No transpose)
- = 'C': apply Q**H (Conjugate transpose)
M — M is INTEGER — The number of rows of the matrix C. M >= 0.
N — N is INTEGER — The number of columns of the matrix C. N >= 0.
K — K is INTEGER — The number of elementary reflectors whose product defines the matrix Q. If SIDE = 'L', M >= K >= 0; if SIDE = 'R', N >= K >= 0.
A — A is COMPLEX*16 array, dimension

(LDA,M) if SIDE = 'L',
(LDA,N) if SIDE = 'R'

The i-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGELQF in the first k rows of its array argument A. A is modified by the routine but restored on exit.

LDA — LDA is INTEGER — The leading dimension of the array A. LDA >= max(1,K).
TAU — TAU is COMPLEX*16 array, dimension (K) — TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGELQF.
C — C is COMPLEX*16 array, dimension (LDC,N) — On entry, the m-by-n matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — LDC is INTEGER — The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX*16 array, dimension

(N) if SIDE = 'L',
(M) if SIDE = 'R'

INFO — ...
INFO is INTEGER
- = 0: slayed, successful exit, we love to see it ✨
- < 0: if INFO = -i, then the i-th argument had an illegal value 😭 (you passed it something cursed, bestie)

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

💜 ZUNMLQ

subroutine zunmlq (character SIDE, character TRANS, integer M, integer N,
    integer K, complex*16, dimension( lda, * ) A, integer LDA, complex*16,
    dimension( * ) TAU, complex*16, dimension( ldc, * ) C, integer LDC,
    complex*16, dimension( * ) WORK, integer LWORK, integer INFO)

🦋 Purpose

okay so ZUNMLQ overwrites the general complex M-by-N matrix C with

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix defined as the product of k elementary reflectors

      Q = H(k)**H . . . H(2)**H H(1)**H

as returned by ZGELQF. Q is of order M if SIDE = 'L' and of order N if SIDE = 'R'. no cap, that's the whole vibe 💅

🌸 Parameters

SIDE — is CHARACTER*1
- = 'L': apply Q or Q**H from the Left;
- = 'R': apply Q or Q**H from the Right.
TRANS — is CHARACTER*1
- = 'N': No transpose, apply Q;
- = 'C': Conjugate transpose, apply Q**H.
M — is INTEGER The number of rows of the matrix C. M >= 0.
N — is INTEGER The number of columns of the matrix C. N >= 0.
K — is INTEGER The number of elementary reflectors whose product defines the matrix Q. If SIDE = 'L', M >= K >= 0; if SIDE = 'R', N >= K >= 0.
A — is COMPLEX*16 array, dimension

                      (LDA,M) if SIDE = 'L',
                      (LDA,N) if SIDE = 'R'

The i-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGELQF in the first k rows of its array argument A. yes bestie, rows here, not columns — read it twice 🫶

LDA — is INTEGER The leading dimension of the array A. LDA >= max(1,K).
TAU — is COMPLEX*16 array, dimension (K) TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGELQF.
C — is COMPLEX*16 array, dimension (LDC,N) On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — is INTEGER The leading dimension of the array C. LDC >= max(1,M).
WORK — is COMPLEX*16 array, dimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK. 👑
LWORK — is INTEGER The dimension of the array WORK. If SIDE = 'L', LWORK >= max(1,N); if SIDE = 'R', LWORK >= max(1,M). For good performance, LWORK should generally be larger. (bigger workspace = better glow-up, that's just how it is ✨)

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. it's giving "just asking, not committing" 💀

INFO — is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

💜 ZUNMQL

subroutine zunmql (character SIDE, character TRANS, integer M, integer N,
    integer K, complex*16, dimension( lda, * ) A, integer LDA, complex*16,
    dimension( * ) TAU, complex*16, dimension( ldc, * ) C, integer LDC,
    complex*16, dimension( * ) WORK, integer LWORK, integer INFO)

🦋 Purpose

ZUNMQL overwrites the general complex M-by-N matrix C with

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix defined as the product of k elementary reflectors

      Q = H(k) . . . H(2) H(1)

as returned by ZGEQLF. Q is of order M if SIDE = 'L' and of order N if SIDE = 'R'. notice the order of the H's flips compared to ZUNMLQ — no transposes on the H's this time, bestie 🎀

🌸 Parameters

SIDE — is CHARACTER*1
- = 'L': apply Q or Q**H from the Left;
- = 'R': apply Q or Q**H from the Right.
TRANS — is CHARACTER*1
- = 'N': No transpose, apply Q;
- = 'C': Conjugate transpose, apply Q**H.
M — is INTEGER The number of rows of the matrix C. M >= 0.
N — is INTEGER The number of columns of the matrix C. N >= 0.
K — is INTEGER The number of elementary reflectors whose product defines the matrix Q. If SIDE = 'L', M >= K >= 0; if SIDE = 'R', N >= K >= 0.
A — is COMPLEX*16 array, dimension (LDA,K) The i-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGEQLF in the last k columns of its array argument A. last k columns, not first — stay woke 🙈
LDA — is INTEGER The leading dimension of the array A. If SIDE = 'L', LDA >= max(1,M); if SIDE = 'R', LDA >= max(1,N).
TAU — is COMPLEX*16 array, dimension (K) TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGEQLF.
C — is COMPLEX*16 array, dimension (LDC,N) On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — is INTEGER The leading dimension of the array C. LDC >= max(1,M).
WORK — is COMPLEX*16 array, dimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — is INTEGER The dimension of the array WORK. If SIDE = 'L', LWORK >= max(1,N); if SIDE = 'R', LWORK >= max(1,M). For good performance, LWORK should generally be larger.

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.

INFO — is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

💜 ZUNMQR

subroutine zunmqr (character SIDE, character TRANS, integer M, integer N,
    integer K, complex*16, dimension( lda, * ) A, integer LDA, complex*16,
    dimension( * ) TAU, complex*16, dimension( ldc, * ) C, integer LDC,
    complex*16, dimension( * ) WORK, integer LWORK, integer INFO)

🦋 Purpose

ZUNMQR overwrites the general complex M-by-N matrix C with

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix defined as the product of k elementary reflectors

      Q = H(1) H(2) . . . H(k)

as returned by ZGEQRF. Q is of order M if SIDE = 'L' and of order N if SIDE = 'R'. the classic, the icon, the one you've probably already met 🔥

🌸 Parameters

SIDE — is CHARACTER*1
- = 'L': apply Q or Q**H from the Left;
- = 'R': apply Q or Q**H from the Right.
TRANS — is CHARACTER*1
- = 'N': No transpose, apply Q;
- = 'C': Conjugate transpose, apply Q**H.
M — is INTEGER The number of rows of the matrix C. M >= 0.
N — is INTEGER The number of columns of the matrix C. N >= 0.
K — is INTEGER The number of elementary reflectors whose product defines the matrix Q. If SIDE = 'L', M >= K >= 0; if SIDE = 'R', N >= K >= 0.
A — is COMPLEX*16 array, dimension (LDA,K) The i-th column must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGEQRF in the first k columns of its array argument A.
LDA — is INTEGER The leading dimension of the array A. If SIDE = 'L', LDA >= max(1,M); if SIDE = 'R', LDA >= max(1,N).
TAU — is COMPLEX*16 array, dimension (K) TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGEQRF.
C — is COMPLEX*16 array, dimension (LDC,N) On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — is INTEGER The leading dimension of the array C. LDC >= max(1,M).
WORK — is COMPLEX*16 array, dimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — is INTEGER The dimension of the array WORK. If SIDE = 'L', LWORK >= max(1,N); if SIDE = 'R', LWORK >= max(1,M). For good performance, LWORK should generally be larger.

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.

INFO — is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🫶 `zunmr2` — the RQ glow-up (unblocked era)

okay so bestie, meet the little sister routine 💅 ZUNMR2 multiplies a general matrix by the unitary matrix from a RQ factorization determined by cgerqf (unblocked algorithm). here's her whole fit:

subroutine zunmr2 (character SIDE, character TRANS, integer M, integer N,
    integer K, complex*16, dimension( lda, * ) A, integer LDA, complex*16,
    dimension( * ) TAU, complex*16, dimension( ldc, * ) C, integer LDC,
    complex*16, dimension( * ) WORK, integer INFO)

Purpose:

ZUNMR2 overwrites the general complex m-by-n matrix C with

      Q * C  if SIDE = 'L' and TRANS = 'N', or

      Q**H* C  if SIDE = 'L' and TRANS = 'C', or

      C * Q  if SIDE = 'R' and TRANS = 'N', or

      C * Q**H if SIDE = 'R' and TRANS = 'C',

where Q is a complex unitary matrix defined as the product of k elementary reflectors

      Q = H(1)**H H(2)**H . . . H(k)**H

as returned by ZGERQF. Q is of order m if SIDE = 'L' and of order n if SIDE = 'R'. the math is mathing ✨

Parameters

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**H from the Left
- = 'R': apply Q or Q**H from the Right
TRANS — TRANS is CHARACTER*1
- = 'N': apply Q (No transpose)
- = 'C': apply Q**H (Conjugate transpose)
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N — N is INTEGER. The number of columns of the matrix C. N >= 0.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q. If SIDE = 'L', M >= K >= 0; if SIDE = 'R', N >= K >= 0.
A — A is COMPLEX*16 array, dimension

                                      (LDA,M) if SIDE = 'L',
                                      (LDA,N) if SIDE = 'R'

The i-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGERQF in the last k rows of its array argument A. A is modified by the routine but restored on exit. yes she borrows your jacket and gives it back, no stains 🧥✨

LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,K).
TAU — TAU is COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGERQF.
C — C is COMPLEX*16 array, dimension (LDC,N). On entry, the m-by-n matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX*16 array, dimension

                                      (N) if SIDE = 'L',
                                      (M) if SIDE = 'R'

INFO — INFO is INTEGER
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 💀

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌸 `zunmr3` — the RZ sister, also unblocked

ZUNMR3 multiplies a general matrix by the unitary matrix from a RZ factorization determined by ctzrzf (unblocked algorithm). different factorization, same energy

subroutine zunmr3 (character SIDE, character TRANS, integer M, integer N,
    integer K, integer L, complex*16, dimension( lda, * ) A, integer LDA,
    complex*16, dimension( * ) TAU, complex*16, dimension( ldc, * ) C,
    integer LDC, complex*16, dimension( * ) WORK, integer INFO)

Purpose:

ZUNMR3 overwrites the general complex m by n matrix C with

      Q * C  if SIDE = 'L' and TRANS = 'N', or

      Q**H* C  if SIDE = 'L' and TRANS = 'C', or

      C * Q  if SIDE = 'R' and TRANS = 'N', or

      C * Q**H if SIDE = 'R' and TRANS = 'C',

where Q is a complex unitary matrix defined as the product of k elementary reflectors

      Q = H(1) H(2) . . . H(k)

as returned by ZTZRZF. Q is of order m if SIDE = 'L' and of order n if SIDE = 'R'.

👀 notice: no **H on the H's this time — zunmr2 had H(1)**H H(2)**H ... H(k)**H and this one is just H(1) H(2) . . . H(k). read it twice, it matters, iykyk.

Parameters

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**H from the Left
- = 'R': apply Q or Q**H from the Right
TRANS — TRANS is CHARACTER*1
- = 'N': apply Q (No transpose)
- = 'C': apply Q**H (Conjugate transpose)
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N — N is INTEGER. The number of columns of the matrix C. N >= 0.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q. If SIDE = 'L', M >= K >= 0; if SIDE = 'R', N >= K >= 0.
L — L is INTEGER. The number of columns of the matrix A containing the meaningful part of the Householder reflectors. If SIDE = 'L', M >= L >= 0, if SIDE = 'R', N >= L >= 0. yes bestie this one has an extra L that zunmr2 doesn't have, don't @ me
A — A is COMPLEX*16 array, dimension

                                      (LDA,M) if SIDE = 'L',
                                      (LDA,N) if SIDE = 'R'

The i-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZTZRZF in the last k rows of its array argument A. A is modified by the routine but restored on exit.

LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,K).
TAU — TAU is COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZTZRZF.
C — C is COMPLEX*16 array, dimension (LDC,N). On entry, the m-by-n matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX*16 array, dimension

                                      (N) if SIDE = 'L',
                                      (M) if SIDE = 'R'

INFO — INFO is INTEGER
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 💀

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Contributors:

A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville, USA shoutout to A. Petitet, we love a credited contributor 💜

Further Details:

literally nothing here, bestie. the heading exists, the content does not. that's the whole vibe. moving on 🙈

👑 `zunmrq` — the blocked RQ queen, she has LWORK

ZUNMRQ

Purpose:

ZUNMRQ overwrites the general complex M-by-N matrix C with

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

a whole little chart, we love a chart ✨

where Q is a complex unitary matrix defined as the product of k elementary reflectors

      Q = H(1)**H H(2)**H . . . H(k)**H

as returned by ZGERQF. Q is of order M if SIDE = 'L' and of order N if SIDE = 'R'.

Parameters

SIDE — SIDE is CHARACTER*1
- = 'L': apply Q or Q**H from the Left;
- = 'R': apply Q or Q**H from the Right.
TRANS — TRANS is CHARACTER*1
- = 'N': No transpose, apply Q;
- = 'C': Conjugate transpose, apply Q**H.
M — M is INTEGER. The number of rows of the matrix C. M >= 0.
N — N is INTEGER. The number of columns of the matrix C. N >= 0.
K — K is INTEGER. The number of elementary reflectors whose product defines the matrix Q. If SIDE = 'L', M >= K >= 0; if SIDE = 'R', N >= K >= 0.
A — A is COMPLEX*16 array, dimension

                                      (LDA,M) if SIDE = 'L',
                                      (LDA,N) if SIDE = 'R'

The i-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGERQF in the last k rows of its array argument A.

heads up: unlike her unblocked cousin zunmr2, this one does NOT say "A is modified by the routine but restored on exit." so don't go assuming that here, bestie 🫶

LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,K).
TAU — TAU is COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGERQF.
C — C is COMPLEX*16 array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
WORK — WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. she tells you how much room she wants, iconic
LWORK — LWORK is INTEGER. The dimension of the array WORK. If SIDE = 'L', LWORK >= max(1,N); if SIDE = 'R', LWORK >= max(1,M). For good performance, LWORK should generally be larger.

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. the classic -1 peek-behind-the-curtain move 💅

INFO — INFO is INTEGER
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value 💀

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🦋 `zunmrz` — and we're just getting started

ZUNMRZ

Purpose:

ZUNMRZ overwrites the general complex M-by-N matrix C with

...and Q itself is a complex unitary matrix built from the product of k elementary reflectors, like:

Q = H(1) H(2) . . . H(k)

...exactly as ZTZRZF hands them back to you. And here's the vibe check on Q's size, bestie: Q is of order M if SIDE = 'L', and of order N if SIDE = 'R'. Periodt. 💅

🫶 Parameters (ZUNMRZ)

SIDE — it's a CHARACTER*1, and it picks a side, obvi:
- = 'L': apply Q or QH from the **Left;
- = 'R': apply Q or QH from the **Right.
TRANS — also CHARACTER*1, and it decides whether we transpose or not:
- = 'N': no transpose, just apply Q;
- = 'C': conjugate transpose, so apply Q**H.
M — INTEGER, the number of rows of the matrix C. Gotta be M >= 0.
N — INTEGER, the number of columns of the matrix C. Also N >= 0, no exceptions.
K — INTEGER, the number of elementary reflectors whose product defines the matrix Q.
- If SIDE = 'L', then M >= K >= 0;
- if SIDE = 'R', then N >= K >= 0.
L — INTEGER, the number of columns of the matrix A that hold the meaningful part of the Householder reflectors.
- If SIDE = 'L', then M >= L >= 0; if SIDE = 'R', then N >= L >= 0.
A — a COMPLEX*16 array, dimension (LDA,M) if SIDE = 'L', or (LDA,N) if SIDE = 'R'. The i-th row has to contain the vector that defines the elementary reflector H(i), for i = 1,2,...,k, exactly as ZTZRZF returned it in the last k rows of its array argument A. Heads up bestie: A is modified by the routine... but it gets restored on exit. 🙈
LDA — INTEGER, the leading dimension of the array A. LDA >= max(1,K).
TAU — a COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZTZRZF.
C — a COMPLEX*16 array, dimension (LDC,N). On entry, it's the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q. (She's changed now, no take-backs 💀)
LDC — INTEGER, the leading dimension of the array C. LDC >= max(1,M).
WORK — a COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, then WORK(1) returns the optimal LWORK. ✨
LWORK — INTEGER, the dimension of the array WORK.
- If SIDE = 'L', LWORK >= max(1,N);
- if SIDE = 'R', LWORK >= max(1,M).
- For good performance, LWORK should generally be larger. (Treat yourself, give it room 🎀)
- If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.
INFO — INTEGER:
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value.

👑 Author (ZUNMRZ)

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

💜 Contributors:

A. Petitet, Computer Science Dept., Univ. of Tenn., Knoxville, USA

🌸 Further Details:

(no extra tea here, bestie — it's literally just vibes)

🦋 subroutine zunmtr

subroutine zunmtr (character SIDE, character UPLO, character TRANS, integer
    M, integer N, complex*16, dimension( lda, * ) A, integer LDA,
    complex*16, dimension( * ) TAU, complex*16, dimension( ldc, * ) C,
    integer LDC, complex*16, dimension( * ) WORK, integer LWORK, integer
    INFO)

ZUNMTR — okay so this one is giving unitary-matrix-applier energy too. 🫶

✨ Purpose:

ZUNMTR overwrites the general complex M-by-N matrix C with

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix of order nq, with nq = m if SIDE = 'L' and nq = n if SIDE = 'R'. Q is defined as the product of nq-1 elementary reflectors, as returned by ZHETRD:

if UPLO = 'U', Q = H(nq-1) . . . H(2) H(1);
if UPLO = 'L', Q = H(1) H(2) . . . H(nq-1).

🌈 Parameters (ZUNMTR)

SIDE — CHARACTER*1:
- = 'L': apply Q or QH from the **Left;
- = 'R': apply Q or QH from the **Right.
UPLO — CHARACTER*1:
- = 'U': the Upper triangle of A contains elementary reflectors from ZHETRD;
- = 'L': the Lower triangle of A contains elementary reflectors from ZHETRD.
TRANS — CHARACTER*1:
- = 'N': no transpose, apply Q;
- = 'C': conjugate transpose, apply Q**H.
M — INTEGER, number of rows of the matrix C. M >= 0.
N — INTEGER, number of columns of the matrix C. N >= 0.
A — a COMPLEX*16 array, dimension (LDA,M) if SIDE = 'L', or (LDA,N) if SIDE = 'R'. These are the vectors that define the elementary reflectors, as returned by ZHETRD.
LDA — INTEGER, the leading dimension of the array A. LDA >= max(1,M) if SIDE = 'L'; LDA >= max(1,N) if SIDE = 'R'.
TAU — a COMPLEX*16 array, dimension (M-1) if SIDE = 'L', or (N-1) if SIDE = 'R'. TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZHETRD.
C — a COMPLEX*16 array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.
LDC — INTEGER, the leading dimension of the array C. LDC >= max(1,M).
WORK — a COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, then WORK(1) returns the optimal LWORK.
LWORK — INTEGER, the dimension of the array WORK.
- If SIDE = 'L', LWORK >= max(1,N);
- if SIDE = 'R', LWORK >= max(1,M).
- For optimum performance, LWORK >= N*NB if SIDE = 'L', and LWORK >= M*NB if SIDE = 'R', where NB is the optimal blocksize. (lowkey a flex, honestly 💅)
- If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.
INFO — INTEGER:
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value.

👑 Author (ZUNMTR)

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🎀 subroutine zupgtr

subroutine zupgtr (character UPLO, integer N, complex*16, dimension( * ) AP,
    complex*16, dimension( * ) TAU, complex*16, dimension( ldq, * ) Q,
    integer LDQ, complex*16, dimension( * ) WORK, integer INFO)

ZUPGTR — she generates the matrix, bestie. Not applies it. Generates it. Main character energy. 👑

✨ Purpose:

ZUPGTR generates a complex unitary matrix Q which is defined as the product of n-1 elementary reflectors H(i) of order n, as returned by ZHPTRD using packed storage:

if UPLO = 'U', Q = H(n-1) . . . H(2) H(1),
if UPLO = 'L', Q = H(1) H(2) . . . H(n-1).

🌸 Parameters (ZUPGTR)

UPLO — CHARACTER*1:
- = 'U': upper triangular packed storage was used in the previous call to ZHPTRD;
- = 'L': lower triangular packed storage was used in the previous call to ZHPTRD.
N — INTEGER, the order of the matrix Q. N >= 0.
AP — a COMPLEX*16 array, dimension (N*(N+1)/2). The vectors which define the elementary reflectors, as returned by ZHPTRD.
TAU — a COMPLEX*16 array, dimension (N-1). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZHPTRD.
Q — a COMPLEX*16 array, dimension (LDQ,N). The N-by-N unitary matrix Q. 💖
LDQ — INTEGER, the leading dimension of the array Q. LDQ >= max(1,N).
WORK — a COMPLEX*16 array, dimension (N-1).
INFO — INTEGER:
- = 0: successful exit 🌟
- < 0: if INFO = -i, the i-th argument had an illegal value.

👑 Author (ZUPGTR)

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

🧚 subroutine zupmtr

subroutine zupmtr (character SIDE, character UPLO, character TRANS, integer
    M, integer N, complex*16, dimension( * ) AP, complex*16, dimension( * )
    TAU, complex*16, dimension( ldc, * ) C, integer LDC, complex*16,
    dimension( * ) WORK, integer INFO)

ZUPMTR — packed-storage edition of the apply-Q-to-C situation. Obsessed. 🦋

✨ Purpose:

ZUPMTR overwrites the general complex M-by-N matrix C with

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix of order nq, with nq = m if SIDE = 'L' and nq = n if SIDE = 'R'. Q is defined as the product of nq-1 elementary reflectors, as returned by ZHPTRD using packed storage:

if UPLO = 'U', Q = H(nq-1) . . . H(2) H(1);
if UPLO = 'L', Q = H(1) H(2) . . . H(nq-1).

🌈 Parameters (ZUPMTR)

SIDE — CHARACTER*1:
- = 'L': apply Q or QH from the **Left;
- = 'R': apply Q or QH from the **Right.
UPLO — CHARACTER*1:
- = 'U': upper triangular packed storage was used in the previous call to ZHPTRD;
- = 'L': lower triangular packed storage was used in the previous call to ZHPTRD.
TRANS — CHARACTER*1:
- = 'N': no transpose, apply Q;
- = 'C': conjugate transpose, apply Q**H.
M — INTEGER, the number of rows of the matrix C. M >= 0.
N — INTEGER, the number of columns of the matrix C. N >= 0.
N — N is INTEGER. It’s the number of columns of the matrix C. N >= 0. periodt. 💖
AP — AP is COMPLEX*16 array, dimension
- (M*(M+1)/2) if SIDE = 'L'
- (N*(N+1)/2) if SIDE = 'R'

These are the vectors which define the elementary reflectors, as returned by ZHPTRD. AP is modified by the routine but restored on exit — the way it gives main character energy and then dips. 🫶

TAU — TAU is COMPLEX*16 array, dimension (M-1) if SIDE = 'L' or (N-1) if SIDE = 'R'. TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZHPTRD. ✨
C — C is COMPLEX*16 array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q. No cap, it gets replaced. 💅
LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M). Respect the leading dimension, bestie. 🌸
WORK — WORK is COMPLEX*16 array, dimension
- (N) if SIDE = 'L'
- (M) if SIDE = 'R'

It's the workspace, doing its little job. 🎀

INFO — INFO is INTEGER
- = 0: successful exit
- < 0: if INFO = -i, the i-th argument had an illegal value

So if INFO is negative, something was not it. 😭

👑 Author 👑

Univ. of Tennessee
Univ. of California Berkeley
Univ. of Colorado Denver
NAG Ltd.

👑 Author (Doxygen's encore) 👑

Generated automatically by Doxygen for LAPACK from the source code.

That's the whole vibe, bestie. This page came from LAPACK version 3.11.0, dated Sun Nov 27 2022, for complex16OTHERcomputational(3). Doxygen auto-generated it from the source code, and honestly? Iconic. 💖

📦 where this page comes from

debian bookworm: liblapack-doc 3.11.0-2 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

complex16OTHERcomputational(3)

💖 complex16OTHERcomputational — LAPACK, section 3 💖

✨ NAME ✨

💖 Detailed Description 💖

✨ Function Documentation ✨

ZBBCSD

🌸 Purpose 🌸

🧚 Parameters 🧚

✨ Internal Parameters ✨

✨ References ✨

✨ Author ✨

✨ Purpose ✨

✨ Parameters ✨

✨ Internal Parameters ✨

✨ Author ✨

🦋 subroutine zgghd3 🦋

🎀 Purpose 🎀

🌸 Parameters 🌸

💜 Author 💜

🌈 Further Details 🌈

🧚 subroutine zgghrd 🧚

🎀 Purpose 🎀

🌸 Parameters 🌸

👑 Author

🔍 Further Details

🌈 subroutine zggqrf

🎯 Purpose

🧩 Parameters

👑 Author

🔍 Further Details

🦋 subroutine zggrqf

🎯 Purpose

🧩 Parameters

👑 Author

🔍 Further Details:

🌸 subroutine zggsvp3

🎯 Purpose:

🛠 Parameters

👑 Author

🔍 Further Details:

🦋 subroutine zgsvj0

🎯 Purpose:

🛠 Parameters

Author 👑

Further Details: 🔥

Contributor: 🌸

Bugs, Examples and Comments: 💌

subroutine zgsvj1 🧚

Purpose: 👑

Parameters 🎀

Author 👑

Contributor: 💖

subroutine zhbgst 🦋

Purpose: 👑

Parameters 🌸

subroutine zhbtrd 🔥

subroutine zhetrd_hb2st 🌈

subroutine zhfrk 🦋

Purpose:

Parameters

Author

subroutine zhpcon 🎀

Purpose:

Parameters

Author

subroutine zhpgst 🌸

Purpose:

Parameters

Author

subroutine zhprfs ⭐

Purpose:

Parameters

💖 Internal Parameters 💖

👑 Author 👑

✨ subroutine zhptrd ✨

🌸 Purpose 🌸

🎀 Parameters 🎀

👑 Author 👑

🦋 Further Details 🦋

✨ subroutine zhptrf ✨

`ZBBCSD`

🌈 subroutine `zggqrf`

🦋 subroutine `zggrqf`

subroutine `zhbtrd` 🔥

subroutine `zhetrd_hb2st` 🌈

✨ `zhptri` / `ZHPTRI` ✨

✨ `zhptrs` / `ZHPTRS` ✨

✨ `zhsein` / `ZHSEIN` ✨

✨ `zhseqr` — the Hessenberg eigenvalue slayer ✨

✨ `zla_lin_berr` — component-wise relative backward error ✨

`subroutine zla_wwaddw` (`integer N, complex16, dimension( ) X, complex16, dimension( ) Y, complex16, dimension( ) W`)

subroutine `zlaed8` 🦋

subroutine `zlals0` 🌸

✨ `zlarscl2` ✨

🦋 `zlarz` 🦋

🫶 `zlarzb` 🫶