/home/abui.../ztrevc3.f(3)

📦 version 3.12.0, in opensuse-leap 16.0

🌸 ZTREVC3 — it's giving eigenvalue slay 💅

okay bestie so this is a page from the LAPACK Library Functions Manual, and the file it lives in is literally:

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

yes that's the whole NAME section, it's just the file path, we love a minimal queen ✨

✨ SYNOPSIS ✨

Functions/Subroutines 🫶

subroutine ZTREVC3 (side, howmny, select, n, t, ldt, vl, ldvl, vr, ldvr,
    mm, m, work, lwork, rwork, lrwork, info)
    ZTREVC3

Function/Subroutine Documentation 📜

subroutine ZTREVC3 (character side, character howmny, logical, dimension( *
    ) select, integer n, complex*16, dimension( ldt, * ) t, integer ldt,
    complex*16, dimension( ldvl, * ) vl, integer ldvl, complex*16,
    dimension( ldvr, * ) vr, integer ldvr, integer mm, integer m,
    complex*16, dimension( * ) work, integer lwork, double precision,
    dimension( * ) rwork, integer lrwork, integer info)
    ZTREVC3

🦋 PURPOSE 🦋

text !> !> ZTREVC3 computes some or all of the right and/or left eigenvectors of !> a complex upper triangular matrix T. !> Matrices of this type are produced by the Schur factorization of !> a complex general matrix: A = Q*T*Q**H, as computed by ZHSEQR. !> !> The right eigenvector x and the left eigenvector y of T corresponding !> to an eigenvalue w are defined by: !> !> T*x = w*x, (y**H)*T = w*(y**H) !> !> where y**H denotes the conjugate transpose of the vector y. !> The eigenvalues are not input to this routine, but are read directly !> from the diagonal of T. !> !> This routine returns the matrices X and/or Y of right and left !> eigenvectors of T, or the products Q*X and/or Q*Y, where Q is an !> input matrix. If Q is the unitary factor that reduces a matrix A to !> Schur form T, then Q*X and Q*Y are the matrices of right and left !> eigenvectors of A. !> !> This uses a Level 3 BLAS version of the back transformation. !>

so basically: you hand it a complex upper triangular matrix T, and it hands you back eigenvectors. no cap. the eigenvalues? not even an input, bestie — it reads them straight off the diagonal of T. iconic behavior honestly 👑

💖 PARAMETERS 💖

  • SIDE — SIDE is CHARACTER*1. the vibe selector 💫
!>          SIDE is CHARACTER*1
!>          = 'R':  compute right eigenvectors only;
!>          = 'L':  compute left eigenvectors only;
!>          = 'B':  compute both right and left eigenvectors.
!>
  • HOWMNY — HOWMNY is CHARACTER*1. how many we doing, girl? 🎀
!>          HOWMNY is CHARACTER*1
!>          = 'A':  compute all right and/or left eigenvectors;
!>          = 'B':  compute all right and/or left eigenvectors,
!>                  backtransformed using the matrices supplied in
!>                  VR and/or VL;
!>          = 'S':  compute selected right and/or left eigenvectors,
!>                  as indicated by the logical array SELECT.
!>
  • SELECT — SELECT is LOGICAL array, dimension (N). the picker-chooser 🌸
!>          SELECT is LOGICAL array, dimension (N)
!>          If HOWMNY = 'S', SELECT specifies the eigenvectors to be
!>          computed.
!>          The eigenvector corresponding to the j-th eigenvalue is
!>          computed if SELECT(j) = .TRUE..
!>          Not referenced if HOWMNY = 'A' or 'B'.
!>
  • N — N is INTEGER. the order of the matrix T. N >= 0. 🔢
!>          N is INTEGER
!>          The order of the matrix T. N >= 0.
!>
  • T — T is COMPLEX*16 array, dimension (LDT,N). the upper triangular matrix T itself. she gets modified, but she's restored on exit — no permanent damage, we promise 🙈
!>          T is COMPLEX*16 array, dimension (LDT,N)
!>          The upper triangular matrix T.  T is modified, but restored
!>          on exit.
!>
  • LDT — LDT is INTEGER. the leading dimension of T. LDT >= max(1,N). 📏
!>          LDT is INTEGER
!>          The leading dimension of the array T. LDT >= max(1,N).
!>
  • VL — VL is COMPLEX*16 array, dimension (LDVL,MM). the left-eigenvector girlie 💜
!>          VL is COMPLEX*16 array, dimension (LDVL,MM)
!>          On entry, if SIDE = 'L' or 'B' and HOWMNY = 'B', VL must
!>          contain an N-by-N matrix Q (usually the unitary matrix Q of
!>          Schur vectors returned by ZHSEQR).
!>          On exit, if SIDE = 'L' or 'B', VL contains:
!>          if HOWMNY = 'A', the matrix Y of left eigenvectors of T;
!>          if HOWMNY = 'B', the matrix Q*Y;
!>          if HOWMNY = 'S', the left eigenvectors of T specified by
!>                           SELECT, stored consecutively in the columns
!>                           of VL, in the same order as their
!>                           eigenvalues.
!>          Not referenced if SIDE = 'R'.
!>
  • LDVL — LDVL is INTEGER. the leading dimension of VL. LDVL >= 1, and if SIDE = 'L' or 'B', then LDVL >= N. 📐
!>          LDVL is INTEGER
!>          The leading dimension of the array VL.
!>          LDVL >= 1, and if SIDE = 'L' or 'B', LDVL >= N.
!>
  • VR — VR is COMPLEX*16 array, dimension (LDVR,MM). the right-eigenvector girlie 💙
!>          VR is COMPLEX*16 array, dimension (LDVR,MM)
!>          On entry, if SIDE = 'R' or 'B' and HOWMNY = 'B', VR must
!>          contain an N-by-N matrix Q (usually the unitary matrix Q of
!>          Schur vectors returned by ZHSEQR).
!>          On exit, if SIDE = 'R' or 'B', VR contains:
!>          if HOWMNY = 'A', the matrix X of right eigenvectors of T;
!>          if HOWMNY = 'B', the matrix Q*X;
!>          if HOWMNY = 'S', the right eigenvectors of T specified by
!>                           SELECT, stored consecutively in the columns
!>                           of VR, in the same order as their
!>                           eigenvalues.
!>          Not referenced if SIDE = 'L'.
!>
  • LDVR — LDVR is INTEGER. the leading dimension of VR. LDVR >= 1, and if SIDE = 'R' or 'B', then LDVR >= N. 📐
!>          LDVR is INTEGER
!>          The leading dimension of the array VR.
!>          LDVR >= 1, and if SIDE = 'R' or 'B', LDVR >= N.
!>
  • MM — MM is INTEGER. the number of columns in VL and/or VR. MM >= M. 🧮
!>          MM is INTEGER
!>          The number of columns in the arrays VL and/or VR. MM >= M.
!>
  • M — M is INTEGER. the number of columns in VL and/or VR that actually get used to store the eigenvectors. if HOWMNY = 'A' or 'B', then M is set to N. each selected eigenvector occupies exactly one column, periodt 💅
!>          M is INTEGER
!>          The number of columns in the arrays VL and/or VR actually
!>          used to store the eigenvectors.
!>          If HOWMNY = 'A' or 'B', M is set to N.
!>          Each selected eigenvector occupies one column.
!>
  • WORK — WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)). the scratchpad ✨
!>          WORK is COMPLEX*16 array, dimension (MAX(1,LWORK))
!>
  • LWORK — LWORK is INTEGER. the dimension of the array WORK. LWORK >= max(1,2*N). for optimum performance, LWORK >= N + 2*N*NB, where NB is the optimal blocksize. 🔥
!>          LWORK is INTEGER
!>          The dimension of array WORK. LWORK >= max(1,2*N).
!>          For optimum performance, LWORK >= N + 2*N*NB, where NB is
!>          the optimal blocksize.
!>
!>          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.
!>
the LWORK = -1 thing is the classic "just tell me how much space you want" move — it queries, pops the answer into the first entry of WORK, and XERBLA stays quiet about LWORK. no drama 🫶
  • RWORK — RWORK is DOUBLE PRECISION array, dimension (LRWORK). the real-valued scratchpad 🍓
!>          RWORK is DOUBLE PRECISION array, dimension (LRWORK)
!>
  • LRWORK — LRWORK is INTEGER. the dimension of array RWORK. LRWORK >= max(1,N). ⭐
!>          LRWORK is INTEGER
!>          The dimension of array RWORK. LRWORK >= max(1,N).
!>
!>          If LRWORK = -1, then a workspace query is assumed; the routine
!>          only calculates the optimal size of the RWORK array, returns
!>          this value as the first entry of the RWORK array, and no error
!>          message related to LRWORK is issued by XERBLA.
!>
same deal as LWORK but for RWORK: LRWORK = -1 means workspace query, optimal size goes in the first entry of RWORK, and XERBLA does not come for LRWORK. we stan a low-drama query 🙌
  • INFO — INFO is INTEGER. the receipts 🧾
!>          INFO is 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 committee showed up, we love a collaborative moment 🌈

🧚 FURTHER DETAILS 🧚

text !> !> The algorithm used in this program is basically backward (forward) !> substitution, with scaling to make the the code robust against !> possible overflow. !> !> Each eigenvector is normalized so that the element of largest !> magnitude has magnitude 1; here the magnitude of a complex number !> (x,y) is taken to be |x| + |y|. !>

(yes, the original really does say "the the" — iconique typo, not touching it 💀)

so: backward (forward) substitution with scaling so the code doesn't overflow, and every eigenvector gets normalized so its largest-magnitude element has magnitude 1 — and just so we're clear, the "magnitude" of a complex number (x,y) here is |x| + |y|. that's the definition, fr fr.

Definition at line 242 of file ztrevc3.f. 📍

🌟 Author (the meta one) 🌟

Generated automatically by Doxygen for LAPACK from the source code. so nobody hand-wrote this page, a robot did, and honestly? she ate 🤖💅

okay that's the whole page bestie, go forth and compute those eigenvectors 💖✨🎀🦋

— LAPACK, Version 3.12.0, /home/abui.../ztrevc3.f(3), mwah 😘

📦 where this page comes from