CHSEIN(3)

CHSEIN(3) ✨ — inverse iteration but make it iconic 💅

okay so bestie, this is CHSEIN(3) from /home/abui...RC/chsein.f(3) and it's literally the LAPACK routine that uses inverse iteration to find specified right and/or left eigenvectors of a complex upper Hessenberg matrix H. it's giving main character energy in the LAPACK library and we're obsessed 💖

---

SYNOPSIS 🎀

subroutine CHSEIN (side, eigsrc, initv, select, n, h, ldh, w, vl, ldvl,
    vr, ldvr, mm, m, work, rwork, ifaill, ifailr, info)
    CHSEIN

and the full signature with all the types, so you know exactly what you're signing up for:

subroutine CHSEIN (character side, character eigsrc, character initv,
    logical, dimension( * ) select, integer n, complex, dimension( ldh, * )
    h, integer ldh, complex, dimension( * ) w, complex, dimension( ldvl, * )
    vl, integer ldvl, complex, dimension( ldvr, * ) vr, integer ldvr,
    integer mm, integer m, complex, dimension( * ) work, real, dimension( *
    ) rwork, integer, dimension( * ) ifaill, integer, dimension( * ) ifailr,
    integer info)
    CHSEIN

---

DESCRIPTION 🦋

okay so the whole vibe of CHSEIN is: it uses inverse iteration to find specified right and/or left eigenvectors of a complex upper Hessenberg matrix H. no cap, that's literally what it does and it slays 💅

the right eigenvector x and the left eigenvector y of the matrix H corresponding to an eigenvalue w are defined by:

H * x = w * x,     y**h * H = w * y**h

where yh denotes the conjugate transpose of the vector y. periodt. that's the math and it ate 🔥

---

PARAMETERS 🌸

SIDE

• SIDE is CHARACTER*1
  • = 'R': compute right eigenvectors only
  • = 'L': compute left eigenvectors only
  • = 'B': compute both right and left eigenvectors

EIGSRC

• EIGSRC is CHARACTER*1 — this one specifies the source of eigenvalues supplied in W:
  • = 'Q': the eigenvalues were found using CHSEQR. so if H has zero subdiagonal elements, and so is block-triangular, then the j-th eigenvalue can be assumed to be an eigenvalue of the block containing the j-th row/column. this property allows CHSEIN to perform inverse iteration on just one diagonal block. lowkey efficient, highkey iconic ✨
  • = 'N': no assumptions are made on the correspondence between eigenvalues and diagonal blocks. in this case, CHSEIN must always perform inverse iteration using the whole matrix H. it's giving thorough, ngl 🫶

INITV

• INITV is CHARACTER*1
  • = 'N': no initial vectors are supplied
  • = 'U': user-supplied initial vectors are stored in the arrays VL and/or VR

SELECT

• SELECT is a LOGICAL array, dimension (N)
  • specifies the eigenvectors to be computed. to select the eigenvector corresponding to the eigenvalue W(j), you gotta set SELECT(j) to .TRUE.. that's the vibe check babe 💅

N

• N is INTEGER
  • the order of the matrix H. N >= 0. no negative energy allowed 🙅‍♀️

H

• H is a COMPLEX array, dimension (LDH,N)
  • the upper Hessenberg matrix H.
  • if a NaN is detected in H, the routine will return with INFO=-6. not me catching NaN and throwing an error 😭

LDH

• LDH is INTEGER
  • the leading dimension of the array H. LDH >= max(1,N).

W

• W is a COMPLEX array, dimension (N)
  • on entry: the eigenvalues of H.
  • on exit: the real parts of W may have been altered since close eigenvalues are perturbed slightly in searching for independent eigenvectors. it's giving "we tweaked it a little for the algorithm" and honestly same 🙈

VL

• VL is a COMPLEX array, dimension (LDVL,MM)
  • on entry: if INITV = 'U' and SIDE = 'L' or 'B', VL must contain starting vectors for the inverse iteration for the left eigenvectors; the starting vector for each eigenvector must be in the same column in which the eigenvector will be stored.
  • on exit: if SIDE = 'L' or 'B', the left eigenvectors specified by SELECT will be stored consecutively in the columns of VL, in the same order as their eigenvalues.
  • if SIDE = 'R', VL is not referenced. it's literally not invited to the right-side party 💀

LDVL

• LDVL is INTEGER
  • the leading dimension of the array VL.
  • LDVL >= max(1,N) if SIDE = 'L' or 'B'; LDVL >= 1 otherwise.

VR

• VR is a COMPLEX array, dimension (LDVR,MM)
  • on entry: if INITV = 'U' and SIDE = 'R' or 'B', VR must contain starting vectors for the inverse iteration for the right eigenvectors; the starting vector for each eigenvector must be in the same column in which the eigenvector will be stored.
  • on exit: if SIDE = 'R' or 'B', the right eigenvectors specified by SELECT will be stored consecutively in the columns of VR, in the same order as their eigenvalues.
  • if SIDE = 'L', VR is not referenced. same energy as VL but flipped 💁‍♀️

LDVR

• LDVR is INTEGER
  • the leading dimension of the array VR.
  • LDVR >= max(1,N) if SIDE = 'R' or 'B'; LDVR >= 1 otherwise.

MM

• 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 the arrays VL and/or VR required to store the eigenvectors (which equals the number of .TRUE. elements in SELECT). so M is literally focused only on the chosen ones, and honestly we respect the selectivity 💅

WORK

• WORK is a COMPLEX array, dimension (N*N)

RWORK

• RWORK is a REAL array, dimension (N)

IFAILL

• IFAIL L is an INTEGER array, dimension (MM)
  • if SIDE = 'L' or 'B', IFAIL L(i) = j > 0 if the left eigenvector in the i-th column of VL (corresponding to the eigenvalue w(j)) failed to converge; IFAIL L(i) = 0 if the eigenvector converged satisfactorily. it's giving "some of y'all didn't make the cut" 💀
  • if SIDE = 'R', IFAIL L is not referenced.

IFAILR

• IFAILR is an INTEGER array, dimension (MM)
  • if SIDE = 'R' or 'B', IFAILR(i) = j > 0 if the right eigenvector in the i-th column of VR (corresponding to the eigenvalue w(j)) failed to converge; IFAILR(i) = 0 if the eigenvector converged satisfactorily. same energy but for the right side 🫶
  • if SIDE = 'L', IFAILR is not referenced.

INFO

• INFO is INTEGER
  • = 0: successful exit 🎉
  • < 0: if INFO = -i, the i-th argument had an illegal value. you tried it and the argument said "not today" 😭
  • > 0: if INFO = i, i is the number of eigenvectors which failed to converge. see IFAIL L and IFAILR for further details. sometimes the vibes just don't converge, bestie 💀

---

AUTHOR 👑

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

these institutions literally collaborated on this and we're grateful 🙏

---

FURTHER DETAILS 🧚

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|. that's the normalization rule and it's giving "we keep it neat" energy 💖

---

DEFINITION 📍

Definition at line 242 of file chsein.f.

---

Generated automatically by Doxygen for LAPACK from the source code. it's giving "the robots wrote this documentation and honestly they ate" 🤖💅

---

and that's the whole page bestie — LAPACK Version 3.12.0, from /home/abui...RC/chsein.f(3), and if you need me I'll be over here normalizing my eigenvectors so the biggest element is 1. periodt. 🎀✨🦋💖