DTREVC(3)

📦 version 3.12.0, in opensuse-leap 16.0

💅 DTREVC(3) — bestie edition ✨

okay so this is from the Library Functions Manual, and the file we're talking about lives at /home/abui...RC/dtrevc.f(3). buckle up, we're doing linear algebra 🎀

🌸 NAME 🌸

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

like, that's the whole name. it's a path. it's giving "I was generated by a build system" and honestly? iconic 💅

✨ SYNOPSIS ✨

Functions/Subroutines

subroutine DTREVC (side, howmny, select, n, t, ldt, vl, ldvl, vr, ldvr,
    mm, m, work, info)
    DTREVC

🦋 Function/Subroutine Documentation 🦋

subroutine DTREVC (character side, character howmny, logical, dimension( * )
    select, integer n, double precision, dimension( ldt, * ) t, integer ldt,
    double precision, dimension( ldvl, * ) vl, integer ldvl, double
    precision, dimension( ldvr, * ) vr, integer ldvr, integer mm, integer m,
    double precision, dimension( * ) work, integer info)

DTREVC — say it with me, bestie 🗣️

💖 Purpose:

!> !> DTREVC computes some or all of the right and/or left eigenvectors of !> a real upper quasi-triangular matrix T. !> Matrices of this type are produced by the Schur factorization of !> a real general matrix: A = Q*T*Q**T, as computed by DHSEQR. !> !> 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 y. !> The eigenvalues are not input to this routine, but are read directly !> from the diagonal blocks 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 orthogonal 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. !>

so real talk: you hand it a real upper quasi-triangular matrix T (the kind you get out of a Schur factorization of a real general matrix, A = Q*T*Q**T, courtesy of DHSEQR), and it hands you back eigenvectors. 🔥 the eigenvalues? not an input, bestie — it reads them straight off the diagonal blocks of T. main character behavior.

the definitions, for the record: T*x = w*x and (y**H)*T = w*(y**H), where y**H is the conjugate transpose of y. and it can give you X and/or Y directly, or the products Q*X and/or Q*Y where Q is an input matrix. if Q is the orthogonal factor that reduces A to Schur form T, then Q*X and Q*Y are the eigenvectors of A. slay 🌈

👑 Parameters 👑

💜 SIDE

!> SIDE is CHARACTER*1 !> = 'R': compute right eigenvectors only; !> = 'L': compute left eigenvectors only; !> = 'B': compute both right and left eigenvectors. !>
  • 'R' — right eigenvectors only, no notes 💅
  • 'L' — left eigenvectors only
  • 'B' — both. go off, get everything 👑

💜 HOWMNY

!> HOWMNY is CHARACTER*1 !> = 'A': compute all right and/or left eigenvectors; !> = 'B': compute all right and/or left eigenvectors, !> backtransformed by the matrices in VR and/or VL; !> = 'S': compute selected right and/or left eigenvectors, !> as indicated by the logical array SELECT. !>
  • 'A' — all of them, the whole collection 🎀
  • 'B' — all of them, but backtransformed by the matrices sitting in VR and/or VL
  • 'S' — only the ones you picked, as flagged by the logical array SELECT

💜 SELECT

!> SELECT is LOGICAL array, dimension (N) !> If HOWMNY = 'S', SELECT specifies the eigenvectors to be !> computed. !> If w(j) is a real eigenvalue, the corresponding real !> eigenvector is computed if SELECT(j) is .TRUE.. !> If w(j) and w(j+1) are the real and imaginary parts of a !> complex eigenvalue, the corresponding complex eigenvector is !> computed if either SELECT(j) or SELECT(j+1) is .TRUE., and !> on exit SELECT(j) is set to .TRUE. and SELECT(j+1) is set to !> .FALSE.. !> Not referenced if HOWMNY = 'A' or 'B'. !>

okay the vibe check here: it's a LOGICAL array of dimension (N). when HOWMNY = 'S', SELECT is literally your shopping list of eigenvectors 🛒

  • if w(j) is a real eigenvalue → that real eigenvector gets computed when SELECT(j) is .TRUE.
  • if w(j) and w(j+1) are the real and imaginary parts of a complex eigenvalue → that complex eigenvector gets computed if either SELECT(j) or SELECT(j+1) is .TRUE., and on exit SELECT(j) is set to .TRUE. and SELECT(j+1) is set to .FALSE. (it picks a winner, respectfully)
not referenced at all if HOWMNY = 'A' or 'B' — it's just vibing in the corner 🙈

💜 N

!> N is INTEGER !> The order of the matrix T. N >= 0. !>

the order of matrix T, and it has to be N >= 0. that's it that's the tweet 💖

💜 T

!> T is DOUBLE PRECISION array, dimension (LDT,N) !> The upper quasi-triangular matrix T in Schur canonical form. !>

a DOUBLE PRECISION array, dimension (LDT,N), holding the upper quasi-triangular matrix T in Schur canonical form. gorgeous, no notes ✨

💜 LDT

!> LDT is INTEGER !> The leading dimension of the array T. LDT >= max(1,N). !>

INTEGER, the leading dimension of T, and it must satisfy LDT >= max(1,N).

💜 VL

!> VL is DOUBLE PRECISION 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 orthogonal matrix Q !> of Schur vectors returned by DHSEQR). !> 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. !> A complex eigenvector corresponding to a complex eigenvalue !> is stored in two consecutive columns, the first holding the !> real part, and the second the imaginary part. !> Not referenced if SIDE = 'R'. !>

DOUBLE PRECISION 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 orthogonal matrix Q of Schur vectors that DHSEQR returned 🫶).

on exit, if SIDE = 'L' or 'B', VL contains:

  • HOWMNY = 'A' → the matrix Y of left eigenvectors of T
  • HOWMNY = 'B' → the matrix Q*Y
  • HOWMNY = 'S' → the left eigenvectors of T specified by SELECT, stored consecutively in the columns of VL, in the same order as their eigenvalues

a complex eigenvector for a complex eigenvalue takes two consecutive columns — first the real part, second the imaginary part. and it's not referenced at all if SIDE = 'R' 💀

💜 LDVL

!> LDVL is INTEGER !> The leading dimension of the array VL. LDVL >= 1, and if !> SIDE = 'L' or 'B', LDVL >= N. !>

leading dimension of VL: LDVL >= 1, and if SIDE = 'L' or 'B', then LDVL >= N.

💜 VR

!> VR is DOUBLE PRECISION 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 orthogonal matrix Q !> of Schur vectors returned by DHSEQR). !> 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. !> A complex eigenvector corresponding to a complex eigenvalue !> is stored in two consecutive columns, the first holding the !> real part and the second the imaginary part. !> Not referenced if SIDE = 'L'. !>

DOUBLE PRECISION array, dimension (LDVR,MM). on entry: if SIDE = 'R' or 'B' and HOWMNY = 'B', VR must contain an N-by-N matrix Q (again, usually the orthogonal matrix Q of Schur vectors from DHSEQR).

on exit, if SIDE = 'R' or 'B', VR contains:

  • HOWMNY = 'A' → the matrix X of right eigenvectors of T
  • HOWMNY = 'B' → the matrix Q*X
  • HOWMNY = 'S' → the right eigenvectors of T specified by SELECT, stored consecutively in the columns of VR, in the same order as their eigenvalues

complex eigenvector, complex eigenvalue → two consecutive columns, real part then imaginary part. and not referenced if SIDE = 'L' 🙈

💜 LDVR

!> LDVR is INTEGER !> The leading dimension of the array VR. LDVR >= 1, and if !> SIDE = 'R' or 'B', LDVR >= N. !>

leading dimension of VR: LDVR >= 1, and if SIDE = 'R' or 'B', then LDVR >= N.

💜 MM

!> MM is INTEGER !> The number of columns in the arrays VL and/or VR. MM >= M. !>

the number of columns in VL and/or VR, with MM >= M.

💜 M

!> 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 real eigenvector occupies one column and each !> selected complex eigenvector occupies two columns. !>

the number of columns in VL and/or VR actually used to store the eigenvectors.

  • if HOWMNY = 'A' or 'B', M is set to N
  • each selected real eigenvector occupies one column, each selected complex eigenvector occupies two columns

💜 WORK

!> WORK is DOUBLE PRECISION array, dimension (3*N) !>

DOUBLE PRECISION array, dimension (3*N). that's the whole description, she's lowkey mysterious 💅

💜 INFO

!> INFO is INTEGER !> = 0: successful exit !> < 0: if INFO = -i, the i-th argument had an illegal value !>
  • = 0 → successful exit, we ate 🍓
  • < 0 → if INFO = -i, the i-th argument had an illegal value. caught in 4k 😭

🌟 Author 🌟

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

the whole squad, credited, as they should be 👑

🔥 Further Details: 🔥

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

so the algorithm is basically backward (forward) substitution, plus scaling so the code stays robust against possible overflow. (yes, the original really does say "the the" — I'm not fixing it, it's part of the lore 💀)

and every eigenvector is normalized so the element of largest magnitude has magnitude 1. for a complex number (x,y), the magnitude is taken to be |x| + |y|. periodt. 🎀

Definition at line 220 of file dtrevc.f.

⭐ Author (again, but make it meta) ⭐

Generated automatically by Doxygen for LAPACK from the source code. beep boop, the robots wrote this one 🤖✨

and that's the whole page, bestie!! 🫶 this was LAPACK, Version 3.12.0, hanging out at /home/abui...RC/dtrevc.f(3) — go forth and compute those eigenvectors, i'm obsessed with you 💖🌸🦋

📦 where this page comes from