SRC/zgeevx.f(3)

💅 NAME

okay so bestie, this is SRC/zgeevx.f — like, the whole file. it lives in the Library Functions Manual and it's the glow-up doc for ZGEEVX, which computes eigenvalues and, if you want them, the left and/or right eigenvectors for GE matrices. no cap. 🦋

---

✨ SYNOPSIS ✨

Functions/Subroutines 🎀

subroutine zgeevx (balanc, jobvl, jobvr, sense, n, a, lda, w, vl, ldvl,
    vr, ldvr, ilo, ihi, scale, abnrm, rconde, rcondv, work, lwork,
    rwork, info)
     ZGEEVX computes the eigenvalues and, optionally, the left and/or
    right eigenvectors for GE matrices

---

🌸 Function/Subroutine Documentation 🌸

subroutine zgeevx (character balanc, character jobvl, character jobvr,
    character sense, integer n, complex*16, dimension( lda, * ) a, integer
    lda, complex*16, dimension( * ) w, complex*16, dimension( ldvl, * ) vl,
    integer ldvl, complex*16, dimension( ldvr, * ) vr, integer ldvr, integer
    ilo, integer ihi, double precision, dimension( * ) scale, double
    precision abnrm, double precision, dimension( * ) rconde, double
    precision, dimension( * ) rcondv, complex*16, dimension( * ) work,
    integer lwork, double precision, dimension( * ) rwork, integer info)

ZGEEVX computes the eigenvalues and, optionally, the left and/or right eigenvectors for GE matrices 💖

Purpose 💫

okay so here's the tea, straight from the source:

ZGEEVX computes for an N-by-N complex nonsymmetric matrix A, the eigenvalues and, optionally, the left and/or right eigenvectors.

Optionally also, it computes a balancing transformation to improve the conditioning of the eigenvalues and eigenvectors (ILO, IHI, SCALE, and ABNRM), reciprocal condition numbers for the eigenvalues (RCONDE), and reciprocal condition numbers for the right eigenvectors (RCONDV).

and the math lore, bestie, it's giving iconic:

The right eigenvector v(j) of A satisfies

A * v(j) = lambda(j) * v(j)

where lambda(j) is its eigenvalue.

The left eigenvector u(j) of A satisfies

u(j)**H * A = lambda(j) * u(j)**H

where u(j)**H denotes the conjugate transpose of u(j).

The computed eigenvectors are normalized to have Euclidean norm equal to 1 and largest component real.

and now the balancing lore — literally so important so pls don't skip:

Balancing a matrix means permuting the rows and columns to make it more nearly upper triangular, and applying a diagonal similarity transformation D * A * D**(-1), where D is a diagonal matrix, to make its rows and columns closer in norm and the condition numbers of its eigenvalues and eigenvectors smaller. The computed reciprocal condition numbers correspond to the balanced matrix. Permuting rows and columns will not change the condition numbers (in exact arithmetic) but diagonal scaling will. For further explanation of balancing, see section 4.10.2 of the LAPACK Users' Guide.

slay. moving on to the parameters 🧚

---

Parameters 🎀

• BALANC — CHARACTER*1. it tells the routine how the input matrix should be diagonally scaled and/or permuted to improve the conditioning of its eigenvalues. your options, bestie:
  • 'N' — do not diagonally scale or permute. we're leaving it alone, respectfully.
  • 'P' — perform permutations to make the matrix more nearly upper triangular. do not diagonally scale.
  • 'S' — diagonally scale the matrix, ie. replace A by D*A*D**(-1), where D is a diagonal matrix chosen to make the rows and columns of A more equal in norm. do not permute.
  • 'B' — both diagonally scale and permute A.

the computed reciprocal condition numbers will be for the matrix after balancing and/or permuting. permuting does not change condition numbers (in exact arithmetic), but balancing does. ✨

• JOBVL — CHARACTER*1.
  • 'N': left eigenvectors of A are not computed.
  • 'V': left eigenvectors of A are computed.

if SENSE = 'E' or 'B', JOBVL must = 'V'. seriously, it's a whole requirement.

• JOBVR — CHARACTER*1.
  • 'N': right eigenvectors of A are not computed.
  • 'V': right eigenvectors of A are computed.

if SENSE = 'E' or 'B', JOBVR must = 'V'. same vibe.

• SENSE — CHARACTER*1. determines which reciprocal condition numbers get computed:
  • 'N': none are computed.
  • 'E': computed for eigenvalues only.
  • 'V': computed for right eigenvectors only.
  • 'B': computed for eigenvalues and right eigenvectors.

if SENSE = 'E' or 'B', both left and right eigenvectors must also be computed (JOBVL = 'V' and JOBVR = 'V'). iykyk 💅

• N — INTEGER. the order of the matrix A. constraint: N >= 0.
• A — COMPLEX*16 array, dimension (LDA,N).
  • on entry, the N-by-N matrix A.
  • on exit, A has been overwritten. if JOBVL = 'V' or JOBVR = 'V', A contains the Schur form of the balanced version of the matrix A. yes it ate your input, that's the deal 🙈
• LDA — INTEGER. the leading dimension of the array A. LDA >= max(1,N).
• W — COMPLEX*16 array, dimension (N). W contains the computed eigenvalues. the main characters 🔥
• VL — COMPLEX*16 array, dimension (LDVL,N).
  • if JOBVL = 'V', the left eigenvectors u(j) are stored one after another in the columns of VL, in the same order as their eigenvalues.
  • if JOBVL = 'N', VL is not referenced. ghosted.
  • u(j) = VL(:,j), the j-th column of VL.
• LDVL — INTEGER. the leading dimension of the array VL. LDVL >= 1; if JOBVL = 'V', LDVL >= N.
• VR — COMPLEX*16 array, dimension (LDVR,N).
  • if JOBVR = 'V', the right eigenvectors v(j) are stored one after another in the columns of VR, in the same order as their eigenvalues.
  • if JOBVR = 'N', VR is not referenced.
  • v(j) = VR(:,j), the j-th column of VR.
• LDVR — INTEGER. the leading dimension of the array VR. LDVR >= 1; if JOBVR = 'V', LDVR >= N.
• ILO — INTEGER. 👑
• IHI — INTEGER. ILO and IHI are integer values determined when A was balanced. the balanced A(i,j) = 0 if I > J and J = 1,...,ILO-1 or I = IHI+1,...,N. so they come as a matching set, bestie 🫶
• SCALE — DOUBLE PRECISION array, dimension (N). the details of the permutations and scaling factors applied when balancing A. if P(j) is the index of the row and column interchanged with row and column j, and D(j) is the scaling factor applied to row and column j, then:

SCALE(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. noted, memorized, screenshotted 📸

• ABNRM — DOUBLE PRECISION. the one-norm of the balanced matrix (the maximum of the sum of absolute values of elements of any column).
• RCONDE — DOUBLE PRECISION array, dimension (N). RCONDE(j) is the reciprocal condition number of the j-th eigenvalue.
• RCONDV — DOUBLE PRECISION array, dimension (N). RCONDV(j) is the reciprocal condition number of the j-th right eigenvector.
• WORK — COMPLEX*16 array, dimension (MAX(1,LWORK)). on exit, if INFO = 0, WORK(1) returns the optimal LWORK. little bonus info for you ✨
• LWORK — INTEGER. the dimension of the array WORK.
  • if SENSE = 'N' or 'E', LWORK >= max(1,2*N), and if SENSE = 'V' or 'B', LWORK >= N*N+2*N.
  • for good performance, LWORK must generally be larger. lowkey always size up, bestie.
  • 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. no yelling from XERBLA, we love that for us 💜
• RWORK — DOUBLE PRECISION array, dimension (2*N).
• INFO — INTEGER.
  • = 0: successful exit 🎉
  • < 0: if INFO = -i, the i-th argument had an illegal value.
  • > 0: if INFO = i, the QR algorithm failed to compute all the eigenvalues, and no eigenvectors or condition numbers have been computed; elements 1:ILO-1 and i+1:N of W contain eigenvalues which have converged.

so if you see a positive INFO, it's not a full slay, but some of W did pull through. 😭

---

👑 Author 👑

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

and the receipts: Definition at line 285 of file zgeevx.f. 🎀

---

⭐ Author (again, but the auto-generated one) ⭐

Generated automatically by Doxygen for LAPACK from the source code. it's giving ✨automation✨

---

okay that's the whole page, bestie — mwah 💋 this was generated automatically by Doxygen for LAPACK, and it's from Version 3.12.0, dated right alongside SRC/zgeevx.f(3). go forth and diagonalize responsibly 🦋🌸💖