ZGGBAL(3)

💅 ZGGBAL(3) — like, the zggbal.f page but make it make sense

okay so real talk, this is zggbal.f, and it lives in the Library Functions Manual (that's the (3) on the tin, bestie — the 3 is giving "compiled library subroutine"). The full glow-up path is:

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

lowkey that /home/abui... shortie in the header is just the terminal being dramatic and eliding the path. the real one is above, no cap.

---

✨ SYNOPSIS ✨

Functions/Subroutines

subroutine ZGGBAL (job, n, a, lda, b, ldb, ilo, ihi, lscale, rscale,
    work, info)

ZGGBAL — that's her. that's the name. 🎀

---

🌸 Function/Subroutine Documentation 🌸

subroutine ZGGBAL (character job, integer n, complex*16, dimension( lda, * )
    a, integer lda, complex*16, dimension( ldb, * ) b, integer ldb, integer
    ilo, integer ihi, double precision, dimension( * ) lscale, double
    precision, dimension( * ) rscale, double precision, dimension( * ) work,
    integer info)

ZGGBAL 💖 (yes, she gets her own heading, she's the main character)

🦋 Purpose 🦋

ZGGBAL balances a pair of general complex matrices (A,B). This involves, first, permuting A and B by similarity transformations to isolate eigenvalues in the first 1 to ILO$-$1 and last IHI+1 to N elements on the diagonal; and second, applying a diagonal similarity transformation to rows and columns ILO to IHI to make the rows and columns as close in norm as possible. Both steps are optional. Balancing may reduce the 1-norm of the matrices, and improve the accuracy of the computed eigenvalues and/or eigenvectors in the generalized eigenvalue problem A*x = lambda*B*x.

okay so literally what she does is take your two matrices (A,B) and give them a little self-care session 🧖 — first she permutes them (similarity transformations, so the eigenvalues stay exactly the same, she's not out here changing your math) to isolate eigenvalues into the first 1 to ILO-1 and last IHI+1 to N spots on the diagonal. then she applies a diagonal similarity transformation to rows and columns ILO to IHI so the rows and columns are as close in norm as possible. both steps are optional, she's flexible like that 🫶.

and why do we care?? because balancing can reduce the 1-norm of the matrices, and that improves the accuracy of the eigenvalues and/or eigenvectors you compute in the generalized eigenvalue problem A*x = lambda*B*x. iconic behavior tbh. ✨

👑 Parameters 👑

• JOB — it's CHARACTER*1, and it picks which operations get performed on A and B:
  • = 'N': none — she just sets ILO = 1, IHI = N, LSCALE(I) = 1.0 and RSCALE(I) = 1.0 for i=1,...,N;
  • = 'P': permute only;
  • = 'S': scale only;
  • = 'B': both permute and scale. 👯‍♀️
• N — INTEGER, the order of the matrices A and B. constraint: N >= 0.
• A — COMPLEX*16 array, dimension (LDA,N). on entry, it's your input matrix A. on exit, A is overwritten by the balanced matrix. if JOB = 'N', A is not referenced 🙈 (she doesn't even look at it).
• LDA — INTEGER, the leading dimension of the array A. LDA >= max(1,N).
• B — COMPLEX*16 array, dimension (LDB,N). on entry, your input matrix B. on exit, B is overwritten by the balanced matrix. if JOB = 'N', B is not referenced 🙈.
• LDB — INTEGER, the leading dimension of the array B. LDB >= max(1,N).
• ILO — INTEGER.
• IHI — INTEGER. ILO and IHI are set to integers such that on exit A(i,j) = 0 and B(i,j) = 0 if i > j and j = 1,...,ILO-1 or i = IHI+1,...,N. if JOB = 'N' or 'S', then ILO = 1 and IHI = N.
• LSCALE — DOUBLE PRECISION array, dimension (N). the deets of the permutations and scaling factors applied to the left side of A and B. if P(j) is the index of the row interchanged with row j, and D(j) is the scaling factor applied to row j, then:

LSCALE(j) = P(j)    for J = 1,...,ILO-1
          = D(j)    for J = ILO,...,IHI
          = P(j)    for J = IHI+1,...,N.

the order in which the interchanges are made is N to IHI+1, then 1 to ILO-1. ⭐

• RSCALE — DOUBLE PRECISION array, dimension (N). same energy but for the right side of A and B. if P(j) is the index of the column interchanged with column j, and D(j) is the scaling factor applied to column j, then:

RSCALE(j) = P(j)    for J = 1,...,ILO-1
          = D(j)    for J = ILO,...,IHI
          = P(j)    for J = IHI+1,...,N.

and again, the order in which the interchanges are made is N to IHI+1, then 1 to ILO-1. 🌈

• WORK — DOUBLE PRECISION array, dimension (lwork). lwork must be at least max(1,6*N) when JOB = 'S' or 'B', and at least 1 when JOB = 'N' or 'P'.
• 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.

(the whole squad, fr fr 🫶)

🔥 Further Details: 🔥

See R.C. WARD, Balancing the generalized eigenvalue problem, SIAM J. Sci. Stat. Comp. 2 (1981), 141-152.

like, go read the receipts if you want the full lore, iykyk 📚

Definition at line 175 of file zggbal.f.

---

🍓 Author 🍓

Generated automatically by Doxygen for LAPACK from the source code. (yes bestie, a robot wrote the skeleton — the ✨vibes✨ are all mine tho)

---

🎀 sign-off time 🎀 LAPACK, Version 3.12.0 — that's the source + version, and the page itself is /home/abui...RC/zggbal.f(3) (the elided-path version of the header line, keeping it cute). date's folded into that footer line too. mwah. 💋 go balance something. 💜