SRC/DEPRECATED/sgegv.f(3)

📦
version 3.12.1 · 2 versions
, in arch rolling

okay so welcome to the Library Functions Manual, section (3) — and yes, we're looking at SRC/DEPRECATED/sgegv.f, which is lowkey living in the deprecated folder but still ate 💅✨

🎀 NAME 🎀

bestie, the name is literally SRC/DEPRECATED/sgegv.f. that's it. that's the whole name. no cap. 🫶

✨ SYNOPSIS ✨

📚 Functions/Subroutines

the main character here is one subroutine, and here's its exact signature — don't come for me, I'm copying it character for character:

subroutine sgegv (jobvl, jobvr, n, a, lda, b, ldb, alphar, alphai, beta,
           vl, ldvl, vr, ldvr, work, lwork, info)

and what does this icon do? SGEGV computes the eigenvalues and, optionally, the left and/or right eigenvectors of a real matrix pair (A,B). periodt. 💖

💖 subroutine sgegv 💖

subroutine sgegv (character jobvl, character jobvr, integer n, real,
    dimension( lda, * ) a, integer lda, real, dimension( ldb, * ) b, integer
    ldb, real, dimension( * ) alphar, real, dimension( * ) alphai, real,
    dimension( * ) beta, real, dimension( ldvl, * ) vl, integer ldvl, real,
    dimension( ldvr, * ) vr, integer ldvr, real, dimension( * ) work,
    integer lwork, integer info)

okay so like, SGEGV computes the eigenvalues and, optionally, the left and/or right eigenvectors of a real matrix pair (A,B). it's giving classic overachiever energy, honestly ✨

🎯 PURPOSE 🎯

⚠️ bestie, listen: this routine is deprecated and has been replaced by routine SGGEV. so yeah, it's iconic but it's also kinda retired. use SGGEV for new stuff, mwah 💋

SGEGV computes the eigenvalues and, optionally, the left and/or right eigenvectors of a real matrix pair (A,B).

given two square matrices A and B, the generalized nonsymmetric eigenvalue problem (GNEP) is to find the eigenvalues lambda and corresponding (non-zero) eigenvectors x such that

A*x = lambda*B*x.

an alternate form is to find the eigenvalues mu and corresponding eigenvectors y such that

mu*A*y = B*y.

these two forms are equivalent with mu = 1/lambda and x = y if neither lambda nor mu is zero. in order to deal with the case that lambda or mu is zero or small, two values alpha and beta are returned for each eigenvalue, such that lambda = alpha/beta and mu = beta/alpha. math girlies stay winning 💅

the vectors x and y in the above equations are right eigenvectors of the matrix pair (A,B). vectors u and v satisfying

u**H*A = lambda*u**H*B  or  mu*v**H*A = v**H*B

are left eigenvectors of (A,B).

note: this routine performs on A and B 🫶

🌸 PARAMETERS 🌸

  • JOBVL — okay so JOBVL is CHARACTER*1 and it's literally your left-eigenvector vibe check:
    • = 'N': do not compute the left generalized eigenvectors. we're not doing left energy today, and that's valid 💀
    • = 'V': compute the left generalized eigenvectors (returned in VL). left queen behavior 👑
  • JOBVR — JOBVR is CHARACTER*1, same deal but for the right side:
    • = 'N': do not compute the right generalized eigenvectors. no right vibes, no problem.
    • = 'V': compute the right generalized eigenvectors (returned in VR). slay, right bestie 💖
  • N — N is INTEGER, and it's the order of the matrices A, B, VL, and VR. literally N >= 0. no cap.
  • A — A is REAL array, dimension (LDA, N). on entry, the matrix A. on exit things get spicy:
    • if JOBVL = 'V' or JOBVR = 'V', then on exit A contains the real Schur form of A from the generalized Schur factorization of the pair (A,B) after balancing. it's giving glow-up ✨
    • if no eigenvectors were computed, then only the diagonal blocks from the Schur form will be correct. the rest is giving "we don't know her" 🙈
    • see SGGHRD and SHGEQZ for details. iykyk.
  • LDA — LDA is INTEGER, the leading dimension of A. and it's gotta be LDA >= max(1,N). rules are rules, bestie.
  • B — B is REAL array, dimension (LDB, N). on entry, the matrix B. on exit:
    • if JOBVL = 'V' or JOBVR = 'V', then on exit B contains the upper triangular matrix obtained from B in the generalized Schur factorization of the pair (A,B) after balancing. triangular and thriving 💅
    • if no eigenvectors were computed, then only those elements of B corresponding to the diagonal blocks from the Schur form of A will be correct. selective correctness, honestly iconic.
    • see SGGHRD and SHGEQZ for details.
  • LDB — LDB is INTEGER, the leading dimension of B. and LDB >= max(1,N). periodt.
  • ALPHAR — ALPHAR is REAL array, dimension (N). the real parts of each scalar alpha defining an eigenvalue of GNEP. real-part representation 🎀
  • ALPHAI — ALPHAI is REAL array, dimension (N). the imaginary parts of each scalar alpha defining an eigenvalue of GNEP. and here's the tea:
    • if ALPHAI(j) is zero, then the j-th eigenvalue is real. simple, real, unbothered.
    • if positive, then the j-th and (j+1)-st eigenvalues are a complex conjugate pair, with ALPHAI(j+1) = -ALPHAI(j). complex conjugate duo, main character energy 🌈
  • BETA — BETA is REAL array, dimension (N). the scalars beta that define the eigenvalues of GNEP. together, the quantities alpha = (ALPHAR(j),ALPHAI(j)) and beta = BETA(j) represent the j-th eigenvalue of the matrix pair (A,B), in one of the forms lambda = alpha/beta or mu = beta/alpha. and bestie, listen: since either lambda or mu may overflow, they should not, in general, be computed. so like, don't do it. danger vibes 💀
  • VL — VL is REAL array, dimension (LDVL,N). if JOBVL = 'V', the left eigenvectors u(j) are stored in the columns of VL, in the same order as their eigenvalues. here's the storage lore:
    • if the j-th eigenvalue is real, then u(j) = VL(:,j).
    • 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).
    • each eigenvector is scaled so that its largest component has abs(real part) + abs(imag. part) = 1, except for eigenvectors corresponding to an eigenvalue with alpha = beta = 0, which are set to zero. zeroed out, respectfully.
    • not referenced if JOBVL = 'N'. if you said no, she stays unread 📵
  • LDVL — LDVL is INTEGER, the leading dimension of the matrix VL. LDVL >= 1, and if JOBVL = 'V', LDVL >= N. conditional slay.
  • VR — VR is REAL array, dimension (LDVR,N). if JOBVR = 'V', the right eigenvectors x(j) are stored in the columns of VR, in the same order as their eigenvalues. same rules, right side:
    • if the j-th eigenvalue is real, then x(j) = VR(:,j).
    • if the j-th and (j+1)-st eigenvalues form a complex conjugate pair, then x(j) = VR(:,j) + i*VR(:,j+1) and x(j+1) = VR(:,j) - i*VR(:,j+1).
    • each eigenvector is scaled so that its largest component has abs(real part) + abs(imag. part) = 1, except for eigenvalues corresponding to an eigenvalue with alpha = beta = 0, which are set to zero.
    • not referenced if JOBVR = 'N'. no right energy? no data.
  • LDVR — LDVR is INTEGER, the leading dimension of the matrix VR. LDVR >= 1, and if JOBVR = 'V', LDVR >= N. periodt.
  • WORK — WORK is REAL array, dimension (MAX(1,LWORK)). on exit, if INFO = 0, WORK(1) returns the optimal LWORK. the workspace bestie we all need 💖
  • LWORK — LWORK is INTEGER, the dimension of the array WORK. and babe, the rules are:
    • LWORK >= max(1,8*N). minimum effort, literally.
    • for good performance, LWORK must generally be larger. do more, get more, glow more ✨
    • to compute the optimal value of LWORK, call ILAENV to get blocksizes (for SGEQRF, SORMQR, and SORGQR.) then compute:
      • NB — MAX of the blocksizes for SGEQRF, SORMQR, and SORGQR;
      • the optimal LWORK is: 2*N + MAX( 6*N, N*(NB+1) ).
    • 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. a sneaky little peek, no error drama.
  • INFO — INFO is INTEGER, the status tea:
    • = 0: successful exit. we ate and left no crumbs 👑
    • < 0: if INFO = -i, the i-th argument had an illegal value. someone broke a rule, not me though.
    • = 1,...,N: the QZ iteration failed. no eigenvectors have been calculated, but ALPHAR(j), ALPHAI(j), and BETA(j) should be correct for j=INFO+1,...,N. partial success is still success-ish 😭
    • > N: errors that usually indicate LAPACK problems:
      • =N+1: error return from SGGBAL
      • =N+2: error return from SGEQRF
      • =N+3: error return from SORMQR
      • =N+4: error return from SORGQR
      • =N+5: error return from SGGHRD
      • =N+6: error return from SHGEQZ (other than failed iteration)
      • =N+7: error return from STGEVC
      • =N+8: error return from SGGBAK (computing VL)
      • =N+9: error return from SGGBAK (computing VR)
      • =N+10: error return from SLASCL (various calls)

🧚 AUTHOR 🧚

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

okay so like, a whole academic friend group wrote this. collective slay 🫶

🔥 FURTHER DETAILS 🔥

✨ Balancing ✨

this driver calls SGGBAL to both permute and scale rows and columns of A and B. the permutations PL and PR are chosen so that PL*A*PR and PL*B*R will be upper triangular except for the diagonal blocks A(i:j,i:j) and B(i:j,i:j), with i and j as close together as possible. the diagonal scaling matrices DL and DR are chosen so that the pair DL*PL*A*PR*DR, DL*PL*B*PR*DR have elements close to one (except for the elements that start out zero.) it's giving organized chaos, honestly 💅

after the eigenvalues and eigenvectors of the balanced matrices have been computed, SGGBAK transforms the eigenvectors back to what they would have been (in perfect arithmetic) if they had not been balanced. reverse glow-up, no cap ✨

🌈 Contents of A and B on Exit 🌈

if any eigenvectors are computed (either JOBVL='V' or JOBVR='V' or both), then on exit the arrays A and B will contain the real Schur form[*] of the versions of A and B. if no eigenvectors are computed, then only the diagonal blocks will be correct.

[*] See SHGEQZ, SGEGS, or read the book , by Golub & van Loan, pub. by Johns Hopkins U. Press. book rec, bestie 📚

definition at line 304 of file sgegv.f.

generated automatically by Doxygen for LAPACK from the source code. it's giving robot-made but make it cute 🤖💖

LAPACK Version 3.12.0 — SRC/DEPRECATED/sgegv.f(3) — byeee, stay slaying those matrices, bestie! 💅✨🎀🦋🌸💖

📦 where this page comes from