geevx(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

✨ geevx(3) ✨ — like, the geevx of the LAPACK library functions manual, bestie 💅

okay so. gather round. this is the manual page for geevx from the Library Functions Manual, and honestly? it's giving eigen-everything. eigenvalues, eigenvectors, condition numbers, balancing — the whole glow-up. no cap, this one's a lot, so let's go 🦋

🌸 NAME 🌸

geevx — ok so it's literally geevx: eig, expert. that's the whole vibe. eig but make it expert. periodt.

✨ SYNOPSIS ✨

💜 Functions

here's the squad — four subroutines, all iconic, all doing the same job in different number flavours (complex, double, single, double-complex):

  • subroutine cgeevx (balanc, jobvl, jobvr, sense, n, a, lda, w, vl, ldvl, vr, ldvr, ilo, ihi, scale, abnrm, rconde, rcondv, work, lwork, rwork, info) — CGEEVX computes the eigenvalues and, optionally, the left and/or right eigenvectors for GE matrices 🫶
  • subroutine dgeevx (balanc, jobvl, jobvr, sense, n, a, lda, wr, wi, vl, ldvl, vr, ldvr, ilo, ihi, scale, abnrm, rconde, rcondv, work, lwork, iwork, info) — DGEEVX computes the eigenvalues and, optionally, the left and/or right eigenvectors for GE matrices ⭐
  • subroutine sgeevx (balanc, jobvl, jobvr, sense, n, a, lda, wr, wi, vl, ldvl, vr, ldvr, ilo, ihi, scale, abnrm, rconde, rcondv, work, lwork, iwork, info) — SGEEVX computes the eigenvalues and, optionally, the left and/or right eigenvectors for GE matrices 🎀
  • 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 🔥

notice how dgeevx and sgeevx have wr, wi (real and imaginary parts, bestie — real matrices give complex answers, we been knew) and complex cgeevx/zgeevx just have w. also iwork vs rwork at the end there. main character details 💅

🌈 Detailed Description 🌈

🧚 Function Documentation

💖 subroutine cgeevx 💖

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

CGEEVX computes the eigenvalues and, optionally, the left and/or right eigenvectors for GE matrices ✨

🎀 Purpose:

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

so like — eigenvalues and eigenvectors and balancing and condition numbers. it's the full package bestie, we love a subroutine that does the most 💅

🌸 Parameters

  • BALANC — BALANC is CHARACTER*1. it tells the routine how to diagonally scale and/or permute the input matrix so its eigenvalues are better conditioned. options are:
!> BALANC is CHARACTER*1 !> Indicates how the input matrix should be diagonally scaled !> and/or permuted to improve the conditioning of its !> eigenvalues. !> = 'N': Do not diagonally scale or permute; !> = '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. !> !> 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. !>

(so 'N' = do nothing, 'P' = permute only, 'S' = scale only, 'B' = both. and heads up: the condition numbers you get back are for the balanced/permuted matrix, and permuting doesn't change them in exact arithmetic but scaling does 🫶)

  • JOBVL — JOBVL is 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'. !>

(you want left eigenvectors? say 'V'. and if SENSE = 'E' or 'B', JOBVL must be 'V' — non-negotiable bestie 😭)

  • JOBVR — JOBVR is 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 deal for the right eigenvectors. SENSE = 'E' or 'B' means JOBVR must be 'V' 💀)

  • SENSE — SENSE is CHARACTER*1. it picks 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'). !>

(if SENSE = 'E' or 'B' you gotta compute both left and right eigenvectors — JOBVL = 'V' and JOBVR = 'V'. them's the rules ✨)

  • N — N is INTEGER. the order of the matrix A. N >= 0. 👑
  • A — A is COMPLEX 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. !>

(⚠️ it gets overwritten, bestie. no take-backs. and if JOBVL = 'V' or JOBVR = 'V', you're left holding the Schur form of the balanced A.)

  • LDA — LDA is INTEGER. the leading dimension of the array A. LDA >= max(1,N). 📏
  • W — W is COMPLEX array, dimension (N). W holds the computed eigenvalues. 💜
  • VL — VL is COMPLEX 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. !> u(j) = VL(:,j), the j-th column of VL. !>

(one per column, in eigenvalue order. u(j) = VL(:,j). and if JOBVL = 'N', VL is literally not even referenced, so don't stress about it 🦋)

  • LDVL — LDVL is INTEGER. the leading dimension of the array VL. LDVL >= 1; if JOBVL = 'V', LDVL >= N. 📐
  • VR — VR is COMPLEX 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. !>

(same energy, right side: v(j) = VR(:,j). JOBVR = 'N' means VR isn't referenced at all 🎀)

  • LDVR — LDVR is INTEGER. the leading dimension of the array VR. LDVR >= 1; if JOBVR = 'V', LDVR >= N. 📐
  • ILO — ILO is INTEGER. (just vibes here, the real explanation is under IHI 👇)
  • IHI — IHI is 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. !>

(these two are the integer values that got figured out while balancing. and the balanced A(i,j) = 0 if I > J and J = 1,...,ILO-1 or I = IHI+1,...,N — like, those corners are zero, periodt 💀)

  • SCALE — SCALE is REAL array, dimension (N).
!> 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. !>

(the receipts of what balancing actually did 🧾. and the interchange order is N to IHI+1, then 1 to ILO-1 — iykyk)

  • ABNRM — ABNRM is REAL. the one-norm of the balanced matrix (the maximum of the sum of absolute values of elements of any column). 🔥
  • RCONDE — RCONDE is REAL array, dimension (N). RCONDE(j) is the reciprocal condition number of the j-th eigenvalue. ⭐
  • RCONDV — RCONDV is REAL array, dimension (N). RCONDV(j) is the reciprocal condition number of the j-th right eigenvector. ⭐
  • WORK — WORK is COMPLEX array, dimension (MAX(1,LWORK)).
!> On exit, if INFO = 0, WORK(1) returns the optimal LWORK. !>

(so if it exits clean with INFO = 0, WORK(1) is telling you the optimal LWORK. free intel 🫶)

  • LWORK — LWORK is INTEGER. the dimension of the array WORK. the rules:
!> 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. !> !> 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. !>

(so: SENSE = 'N' or 'E' → LWORK >= max(1,2*N); SENSE = 'V' or 'B' → LWORK >= N*N+2*N. and for good performance, LWORK must generally be larger — treat it like a recommendation from your friend who's always right. also!! LWORK = -1 means workspace query: it only calculates the optimal size of the WORK array, returns it as the first entry of WORK, and XERBLA won't throw any LWORK-related error at you. iconic 😌)

  • RWORK — RWORK is REAL array, dimension (2*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 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. !>

(the vibe check report: 0 = we slayed, < 0 = argument -i was illegal, > 0 = the QR algorithm couldn't get all the eigenvalues, so no eigenvectors or condition numbers were computed — only 1:ILO-1 and i+1:N of W have converged eigenvalues. so close bestie 😭)

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

(they ate, fr fr 💜)

⭐ Definition

Definition at line 285 of file cgeevx.f.

okay that's cgeevx down 🎀 — and there's more coming, so don't go anywhere…

   subroutine dgeevx (character balanc, character jobvl, character jobvr,
       character sense, integer n, double precision, dimension( lda, * ) a,
       integer lda, double precision, dimension( * ) wr, double precision,
       dimension( * ) wi, double precision, dimension( ldvl, * ) vl, integer
       ldvl, double precision, dimension( ldvr, * ) vr, integer ldvr, integer
       ilo, integer ihi, double precision, dimension( * ) scale, double
       precision abnrm, double precision, dimension( * ) rconde, double
       precision, dimension( * ) rcondv, double precision, dimension( * ) work,
       integer lwork, integer, dimension( * ) iwork, integer info)

✨ DGEEVX computes the eigenvalues and, optionally, the left and/or right eigenvectors for GE matrices. ✨

✨ Purpose ✨

okay so bestie, here's the whole vibe: DGEEVX computes, for an N-by-N real nonsymmetric matrix A, the eigenvalues and — if you want them — the left and/or right eigenvectors. 💅

Optionally, it also 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). It's giving "I did the math and also the glow-up." ✨

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. No cap, that's the standard.

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

✨ Parameters ✨

  • BALANC — is a CHARACTER*1 that tells the routine how the input matrix should be diagonally scaled and/or permuted to improve the conditioning of its eigenvalues.
    • 'N': Do not diagonally scale or permute;
    • 'P': Perform permutations to make the matrix more nearly upper triangular. Do not diagonally scale;
    • 'S': Diagonally scale the matrix, i.e. 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.

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 — is a 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'. 🎀

  • JOBVR — is a 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'. 🎀

  • SENSE — is a CHARACTER*1 that determines which reciprocal condition numbers are 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'). 👑

  • N — is INTEGER. The order of the matrix A. N >= 0.
  • A — is DOUBLE PRECISION 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 real Schur form of the balanced version of the input matrix A. 💅
  • LDA — is INTEGER. The leading dimension of the array A. LDA >= max(1,N).
  • WR — is DOUBLE PRECISION array, dimension (N).
  • WI — is DOUBLE PRECISION array, dimension (N). WR and WI contain the real and imaginary parts, respectively, of the computed eigenvalues. Complex conjugate pairs of eigenvalues will appear consecutively with the eigenvalue having the positive imaginary part first. 🌸
  • VL — is DOUBLE PRECISION 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. If the j-th eigenvalue is real, then u(j) = VL(:,j), the j-th column of VL. If the j-th and (j+1)-st eigenvalues form a complex conjugate pair, then u(j) = VL(:,j) + i*VL(:,j+1) and u(j+1) = VL(:,j) - i*VL(:,j+1). 🦋
  • LDVL — is INTEGER. The leading dimension of the array VL. LDVL >= 1; if JOBVL = 'V', LDVL >= N.
  • VR — is DOUBLE PRECISION 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. If the j-th eigenvalue is real, then v(j) = VR(:,j), the j-th column of VR. If the j-th and (j+1)-st eigenvalues form a complex conjugate pair, then v(j) = VR(:,j) + i*VR(:,j+1) and v(j+1) = VR(:,j) - i*VR(:,j+1). 🦋
  • LDVR — is INTEGER. The leading dimension of the array VR. LDVR >= 1, and if JOBVR = 'V', LDVR >= N.
  • ILO — is INTEGER.
  • IHI — is 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. 🌈
  • SCALE — is DOUBLE PRECISION array, dimension (N). 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. ⭐
  • ABNRM — is DOUBLE PRECISION. The one-norm of the balanced matrix (the maximum of the sum of absolute values of elements of any column). 🔥
  • RCONDE — is DOUBLE PRECISION array, dimension (N). RCONDE(j) is the reciprocal condition number of the j-th eigenvalue. 💖
  • RCONDV — is DOUBLE PRECISION array, dimension (N). RCONDV(j) is the reciprocal condition number of the j-th right eigenvector. 💖
  • WORK — is DOUBLE PRECISION 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 SENSE = 'N' or 'E', LWORK >= max(1,2*N), and if JOBVL = 'V' or JOBVR = 'V', LWORK >= 3*N. If SENSE = 'V' or 'B', LWORK >= N*(N+6). For good performance, LWORK must 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. 🫶

  • IWORK — is INTEGER array, dimension (2*N-2). If SENSE = 'N' or 'E', not referenced.
  • INFO — is 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 WR and WI contain eigenvalues which have converged. 💀

✨ Author ✨

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

✨ Definition ✨

Definition at line 303 of file dgeevx.f.

🦋 sgeevx — the real-valued one

subroutine sgeevx (character balanc, character jobvl, character jobvr,
    character sense, integer n, real, dimension( lda, * ) a, integer lda,
    real, dimension( * ) wr, real, dimension( * ) wi, real, dimension( ldvl,
    * ) vl, integer ldvl, real, dimension( ldvr, * ) vr, integer ldvr,
    integer ilo, integer ihi, real, dimension( * ) scale, real abnrm, real,
    dimension( * ) rconde, real, dimension( * ) rcondv, real, dimension( * )
    work, integer lwork, integer, dimension( * ) iwork, integer info)

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

✨ Purpose ✨

okay so bestie, picture this — you hand SGEEVX an N-by-N real nonsymmetric matrix A, and it gives you back:

  • the eigenvalues 🔥
  • and, if you want them, the left and/or right eigenvectors 🎀

And that's not even the whole slay. Optionally it also 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) ✨
  • reciprocal condition numbers for the right eigenvectors (RCONDV) 🦋

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). yes, the H is doing a whole lot of work there, ik 😭

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

Now, balancing a matrix — let me put you on, because this is the part people skip and then get confused: balancing means permuting the rows and columns to make the matrix 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 📚

🎀 Parameters 🎀

  • BALANC — CHARACTER*1. Indicates how the input matrix should be diagonally scaled and/or permuted to improve the conditioning of its eigenvalues.
    • = 'N': Do not diagonally scale or permute;
    • = 'P': Perform permutations to make the matrix more nearly upper triangular. Do not diagonally scale;
    • = 'S': Diagonally scale the matrix, i.e. 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.

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. lowkey important, don't skip 🫶

  • 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'. no wiggle room, bestie 💀

  • 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 energy 👑

  • SENSE — CHARACTER*1. Determines which reciprocal condition numbers are 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'). it's giving "you can't have one without the other" 😌

  • N — INTEGER. The order of the matrix A. N >= 0.
  • A — REAL 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 real Schur form of the balanced version of the input matrix A. yeah she got a whole new look, that's the vibe check passing 🌸
  • LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,N).
  • WR — REAL array, dimension (N).
  • WI — REAL array, dimension (N). WR and WI contain the real and imaginary parts, respectively, of the computed eigenvalues. Complex conjugate pairs of eigenvalues will appear consecutively with the eigenvalue having the positive imaginary part first. ik, it's a cute little pairing rule 🍓
  • VL — REAL 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. If the j-th eigenvalue is real, then u(j) = VL(:,j), the j-th column of VL. If the j-th and (j+1)-st eigenvalues form a complex conjugate pair, then u(j) = VL(:,j) + i*VL(:,j+1) and u(j+1) = VL(:,j) - i*VL(:,j+1). two columns, one vibe 💜
  • LDVL — INTEGER. The leading dimension of the array VL. LDVL >= 1; if JOBVL = 'V', LDVL >= N.
  • VR — REAL 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. If the j-th eigenvalue is real, then v(j) = VR(:,j), the j-th column of VR. If the j-th and (j+1)-st eigenvalues form a complex conjugate pair, then v(j) = VR(:,j) + i*VR(:,j+1) and v(j+1) = VR(:,j) - i*VR(:,j+1). mirror of VL, main character energy 🦋
  • LDVR — INTEGER. The leading dimension of the array VR. LDVR >= 1, and 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. those zeros are not an accident, they're the point ✨
  • SCALE — REAL array, dimension (N). 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. yes the order matters, do not come for me 😤

  • ABNRM — REAL. The one-norm of the balanced matrix (the maximum of the sum of absolute values of elements of any column).
  • RCONDE — REAL array, dimension (N). RCONDE(j) is the reciprocal condition number of the j-th eigenvalue.
  • RCONDV — REAL array, dimension (N). RCONDV(j) is the reciprocal condition number of the j-th right eigenvector.
  • WORK — REAL array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  • LWORK — INTEGER. The dimension of the array WORK. If SENSE = 'N' or 'E', LWORK >= max(1,2*N), and if JOBVL = 'V' or JOBVR = 'V', LWORK >= 3*N. If SENSE = 'V' or 'B', LWORK >= N*(N+6). For good performance, LWORK must generally be larger. (bigger workspace = happier routine, that's just facts 🔥)

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. so you can ask "how much do u need bestie" without getting yelled at, iconic 🙈

  • IWORK — INTEGER array, dimension (2*N-2). If SENSE = 'N' or 'E', not referenced.
  • 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 WR and WI contain eigenvalues which have converged. 😭 partial results, but like, at least you got some of them

👑 Author 👑

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

Definition at line 303 of file sgeevx.f.

🌈 zgeevx — now in complex 💅

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 ✨

...and the math bits? lowkey the whole point, so let's go 🫶

The right eigenvector v(j) of A satisfies

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

where lambda(j) is its eigenvalue. Slay.

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). Bestie, that conjugate transpose is doing so much work, respect.

The computed eigenvectors are normalized to have Euclidean norm equal to 1 and largest component real. Periodt — that's the normalization, don't come for me.

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

✨ Parameters ✨

BALANC

BALANC is CHARACTER*1 — it indicates how the input matrix should be diagonally scaled and/or permuted to improve the conditioning of its eigenvalues. The vibe check, basically:

  • 'N' — Do not diagonally scale or permute;
  • '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.

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

JOBVL is 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'. Not optional, bestie, it's a rule.

JOBVR

JOBVR is 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 deal, no cap.

SENSE

SENSE is CHARACTER*1 — determines which reciprocal condition numbers are 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'). Like, you literally can't skip them, that's the whole deal. 💅

N

N is INTEGER — the order of the matrix A. N >= 0. (Zero is legal, don't be weird about it.)

A

A is 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. 🦋

She's been through some things, okay — your input A is gone-gone on the way out. Plan accordingly.

LDA

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

W

W is COMPLEX*16 array, dimension (N). W contains the computed eigenvalues. The main characters, honestly. 👑

VL

VL is 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.

u(j) = VL(:,j), the j-th column of VL. Column energy, iconic.

LDVL

LDVL is INTEGER — the leading dimension of the array VL. LDVL >= 1; if JOBVL = 'V', LDVL >= N.

VR

VR is 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. Same energy, other side. 🌸

LDVR

LDVR is INTEGER — the leading dimension of the array VR. LDVR >= 1; if JOBVR = 'V', LDVR >= N.

ILO

ILO is INTEGER. That's it, that's the entry — it's explained with its buddy below. 🙈

IHI

IHI is 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. Free zeros, we love to see it.

SCALE

SCALE is DOUBLE PRECISION array, dimension (N).

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. Yeah, it goes backwards first — read it twice, it's fine, I had to. 😭

ABNRM

ABNRM is DOUBLE PRECISION — the one-norm of the balanced matrix (the maximum of the sum of absolute values of elements of any column). Big number, one column at a time. 🔥

RCONDE

RCONDE is DOUBLE PRECISION array, dimension (N). RCONDE(j) is the reciprocal condition number of the j-th eigenvalue.

RCONDV

RCONDV is DOUBLE PRECISION array, dimension (N). RCONDV(j) is the reciprocal condition number of the j-th right eigenvector.

WORK

WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. She snitches on the best workspace size for you, we stan a helpful queen. ✨

LWORK

LWORK is 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. (Like, minimum viable is not the flex.)

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. Sneaky little -1 trick, lowkey my fave.

RWORK

RWORK is DOUBLE PRECISION array, dimension (2*N). Just vibes and scratch space, that's all it says, that's all I got. 🍓

INFO

INFO is 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.
If you get INFO > 0 you got a partial result — a little bit of slay, but not the full slay. Check those W ranges before you trust anything downstream. 💀

🫶 Author 🫶

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

📍 Definition at line 285 of file zgeevx.f

🧚 Author 🧚

Generated automatically by Doxygen for LAPACK from the source code.

And that's the whole page, bestie — that was LAPACK Version 3.12.0, geevx(3), generated from the source code, and you made it all the way to the end so honestly you're the main character here. Go get those eigenvalues. 🌈💜

📦 where this page comes from