ZGGHRD(3)

🦋 ZGGHRD(3) 🦋

okay bestie so this is a page from the Library Functions Manual — it's literally all about zgghrd.f, which lives at /home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/SRC/zgghrd.f. yes that path is a whole mouthful, i know. 💀

---

✨ NAME ✨

/home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/SRC/zgghrd.f

like. that's the name. that's the whole name. it's giving "my file system is my personality". 🎀

---

🌸 SYNOPSIS 🌸

Functions/Subroutines

subroutine ZGGHRD (compq, compz, n, ilo, ihi, a, lda, b, ldb, q, ldq, z,
    ldz, info)
    ZGGHRD

one subroutine, fourteen arguments, zero chill. she's iconic like that. 💅

---

👑 Function/Subroutine Documentation 👑

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:

ok so here's the vibe check on what ZGGHRD actually does:

!>
!> 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.
!>
!> 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.
!>

so basically: A goes Hessenberg, B stays triangular, and Q and Z are built out of Givens rotations — either freshly formed or multiplied into your existing Q1 and Z1. it's giving glow-up transformation ✨🦋

---

🍓 Parameters

COMPQ

!>          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.
!>

• 'N' — no Q for you, we're not computing it, moving on 💅
• 'I' — Q starts as the unit matrix and you get the real unitary Q back, slay
• 'V' — you bring a unitary Q1 in on entry, and you get Q1*Q back out. teamwork fr fr 🫶

COMPZ

!>          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.
!>

same energy as COMPQ but for Z, and honestly she deserves her own moment:

• 'N' — skip Z entirely
• 'I' — Z gets initialized to the unit matrix, and the unitary Z is what you get back
• 'V' — you hand in Z1 and receive Z1*Z 💖

N

!>          N is INTEGER
!>          The order of the matrices A and B.  N >= 0.
!>

the order of A and B. must be N >= 0, no negative nonsense allowed. 🚫

ILO

!>          ILO is INTEGER
!>

IHI

!>          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.
!>

these two are a package deal bestie 🎀 they mark the rows & columns of A that actually get reduced. it's assumed A is already upper triangular in rows and columns 1:ILO-1 and IHI+1:N — like, do not make her check, she trusts you.

normally you get these from a previous call to ZGGBAL. no previous call? then set them to 1 and N respectively.

constraints, and yes she's strict:

• 1 <= ILO <= IHI <= N if N > 0
• ILO=1 and IHI=0 if N=0

A

!>          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.
!>

entry: your N-by-N general matrix. exit: the upper triangle + first subdiagonal get overwritten with the upper Hessenberg matrix H, and everything else is set to zero. she eats and leaves no crumbs 😭🔥

LDA

!>          LDA is INTEGER
!>          The leading dimension of the array A.  LDA >= max(1,N).
!>

leading dimension of A. LDA >= max(1,N). periodt.

B

!>          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.
!>

entry: N-by-N upper triangular B. exit: upper triangular T = Q**H B Z, with everything below the diagonal zeroed out. clean. 💅

LDB

!>          LDB is INTEGER
!>          The leading dimension of the array B.  LDB >= max(1,N).
!>

LDB >= max(1,N). that's the whole requirement, love that for us.

Q

!>          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'.
!>

• entry, if COMPQ = 'V': the unitary matrix Q1, typically from the QR factorization of B
• exit, if COMPQ='I': the unitary matrix Q
• exit, if COMPQ = 'V': the product Q1*Q
• not referenced at all if COMPQ='N' 🙈

LDQ

!>          LDQ is INTEGER
!>          The leading dimension of the array Q.
!>          LDQ >= N if COMPQ='V' or 'I'; LDQ >= 1 otherwise.
!>

LDQ >= N when COMPQ is 'V' or 'I'; LDQ >= 1 otherwise. conditional queen 👑

Z

!>          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'.
!>

• entry, if COMPZ = 'V': the unitary matrix Z1
• exit, if COMPZ='I': the unitary matrix Z
• exit, if COMPZ = 'V': the product Z1*Z
• not referenced if COMPZ='N' 🦋

LDZ

!>          LDZ is INTEGER
!>          The leading dimension of the array Z.
!>          LDZ >= N if COMPZ='V' or 'I'; LDZ >= 1 otherwise.
!>

LDZ >= N when COMPZ is 'V' or 'I'; LDZ >= 1 otherwise. twins with LDQ, honestly.

INFO

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

• = 0 — we did it, successful exit, celebration time 🎉
• < 0 — uh oh. if INFO = -i, the i-th argument had an illegal value. she's calling you out by index number 💀

---

💜 Author

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

four whole institutions on the credits. group project but make it academia 👑

---

🎀 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).
!>

key detail bestie: this is an unblocked reduction. that's the Matrix Computations book by Golub and van Loan (Johns Hopkins Press) describing it, iykyk 📚✨

---

⭐ Definition

Definition at line 202 of file zgghrd.f.

---

🌈 Author

Generated automatically by Doxygen for LAPACK from the source code.

(no human wrote this part, Doxygen just spawned it, main character energy of a build tool honestly 🙈)

---

okay and that's the whole page!! no cap, every flag, every bound, every zeroed-out element, all documented. if you got this far you're literally a LAPACK girlie now 🫶💖

---

LAPACK · Version 3.12.0 · /home/abui...RC/zgghrd.f(3) — that's the footer bestie, signed, sealed, slayed. 💅🎀