ZHPGVX(3)

📦 version 3.12.0, in opensuse-leap 16.0

🦋 ZHPGVX(3) 🦋

okay so bestie, welcome to the manual page for ZHPGVX — and yes, the manual name is Library Functions Manual, and the file it lives in is literally /home/abui...RC/zhpgvx.f(3). iykyk. let's get into it 💅

✨ NAME ✨

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

like... that's the whole name. it's giving "my full legal name is my home address" energy and honestly? iconic. 🎀

🌸 SYNOPSIS 🌸

Functions/Subroutines

the one and only:

subroutine ZHPGVX (itype, jobz, range, uplo, n, ap, bp, vl, vu, il, iu,
    abstol, m, w, z, ldz, work, rwork, iwork, ifail, info)

ZHPGVX — that's her. that's the main character. 👑

💖 Function/Subroutine Documentation 💖

the actual signature, in all its glory ✨

subroutine ZHPGVX (integer itype, character jobz, character range, character
    uplo, integer n, complex*16, dimension( * ) ap, complex*16, dimension( *
    ) bp, double precision vl, double precision vu, integer il, integer iu,
    double precision abstol, integer m, double precision, dimension( * ) w,
    complex*16, dimension( ldz, * ) z, integer ldz, complex*16, dimension( *
    ) work, double precision, dimension( * ) rwork, integer, dimension( * )
    iwork, integer, dimension( * ) ifail, integer info)

ZHPGVX 💫

Purpose 🫶

okay so here's the tea. (straight from the source, bestie:)

!>
!> ZHPGVX computes selected eigenvalues and, optionally, eigenvectors
!> of a complex generalized Hermitian-definite eigenproblem, of the form
!> A*x=(lambda)*B*x,  A*Bx=(lambda)*x,  or B*A*x=(lambda)*x.  Here A and
!> B are assumed to be Hermitian, stored in packed format, and B is also
!> positive definite.  Eigenvalues and eigenvectors can be selected by
!> specifying either a range of values or a range of indices for the
!> desired eigenvalues.
!>

so like — eigenvalues, eigenvectors, optionally, your choice. she's flexible. she's that subroutine. and yes, A and B are Hermitian, stored in packed format, and B has to be positive definite (non-negotiable, bestie, it's literally in the contract 😭).

🌈 Parameters 🌈

ITYPE 💜

ITYPE is INTEGER. it tells us which flavor of problem we're solving:

  • = 1: A*x = (lambda)*B*x
  • = 2: A*B*x = (lambda)*x
  • = 3: B*A*x = (lambda)*x

pick your fighter. 🥊

JOBZ 🎀

JOBZ is CHARACTER*1:

  • = 'N': compute eigenvalues only;
  • = 'V': compute eigenvalues and eigenvectors.

no in-between. she's not doing "just a little eigenvectors." 💅

RANGE ⭐

RANGE is CHARACTER*1:

  • = 'A': all eigenvalues will be found;
  • = 'V': all eigenvalues in the half-open interval (VL,VU] will be found;
  • = 'I': the IL-th through IU-th eigenvalues will be found.

note the half-open interval, bestie — (VL,VU]. the bracket matters. respect the bracket. 🙈

UPLO 🦋

UPLO is CHARACTER*1:

  • = 'U': Upper triangles of A and B are stored;
  • = 'L': Lower triangles of A and B are stored.

pick a triangle, any triangle. 🎔

N 🌸

N is INTEGER — the order of the matrices A and B. N >= 0.

that's it. that's the whole vibe check. ✨

AP 🔥

AP is COMPLEX*16 array, dimension (N*(N+1)/2).

On entry: the upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. the j-th column of A is stored in the array AP like this:

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.
⚠️ On exit, the contents of AP are destroyed. she ate and left no crumbs. gone. do not come looking for your original A, bestie, i'm serious 😭

BP 💀

BP is COMPLEX*16 array, dimension (N*(N+1)/2).

On entry: the upper or lower triangle of the Hermitian matrix B, packed columnwise in a linear array. the j-th column of B is stored in the array BP like this:

if UPLO = 'U', BP(i + (j-1)*j/2) = B(i,j) for 1<=i<=j;
if UPLO = 'L', BP(i + (j-1)*(2*n-j)/2) = B(i,j) for j<=i<=n.

On exit: the triangular factor U or L from the Cholesky factorization B = U**H*U or B = L*L**H, in the same storage format as B.

so BP also gets rewritten, but at least it gets a glow-up instead of just being deleted. 🫶

VL 🍓

VL is DOUBLE PRECISION.

if RANGE='V', the lower bound of the interval to be searched for eigenvalues. VL < VU.

Not referenced if RANGE = 'A' or 'I'.

VU 🍓

VU is DOUBLE PRECISION.

if RANGE='V', the upper bound of the interval to be searched for eigenvalues. VL < VU.

Not referenced if RANGE = 'A' or 'I'.

(and YES, VL < VU is not a suggestion, it's a requirement. strict inequality. she's not playing. 💅)

IL 🌟

IL is INTEGER.

if RANGE='I', the index of the smallest eigenvalue to be returned.

1 <= IL <= IU <= N, if N > 0; IL = 1 and IU = 0 if N = 0.

Not referenced if RANGE = 'A' or 'V'.

IU 🌟

IU is INTEGER.

if RANGE='I', the index of the largest eigenvalue to be returned.

1 <= IL <= IU <= N, if N > 0; IL = 1 and IU = 0 if N = 0.

Not referenced if RANGE = 'A' or 'V'.

ABSTOL 🧚

ABSTOL is DOUBLE PRECISION — the absolute error tolerance for the eigenvalues. an approximate eigenvalue is accepted as converged when it is determined to lie in an interval [a,b] of width less than or equal to

ABSTOL + EPS *   max( |a|,|b| ) ,

where EPS is the machine precision. if ABSTOL is less than or equal to zero, then EPS*|T| will be used in its place, where |T| is the 1-norm of the tridiagonal matrix obtained by reducing AP to tridiagonal form.

eigenvalues will be computed most accurately when ABSTOL is set to twice the underflow threshold 2*DLAMCH('S'), not zero.

💀 if this routine returns with INFO>0, indicating that some eigenvectors did not converge, try setting ABSTOL to 2*DLAMCH('S'). like, that's the move. that's the fix. write it down bestie.

M 👑

M is INTEGER — the total number of eigenvalues found. 0 <= M <= N.

if RANGE = 'A', M = N, and if RANGE = 'I', M = IU-IL+1.

the receipts, basically. 💅

W 🎀

W is DOUBLE PRECISION array, dimension (N).

on normal exit, the first M elements contain the selected eigenvalues in ascending order.

ascending. sorted. organized. she's a virgo. ✨

Z 🦋

Z is COMPLEX*16 array, dimension (LDZ, N).

if JOBZ = 'N', then Z is not referenced.

if JOBZ = 'V', then if INFO = 0, the first M columns of Z contain the orthonormal eigenvectors of the matrix A corresponding to the selected eigenvalues, with the i-th column of Z holding the eigenvector associated with W(i). the eigenvectors are normalized as follows:

if ITYPE = 1 or 2, Z**H*B*Z = I;
if ITYPE = 3, Z**H*inv(B)*Z = I.

if an eigenvector fails to converge, then that column of Z contains the latest approximation to the eigenvector, and the index of the eigenvector is returned in IFAIL.

🫶 Note: the user must ensure that at least max(1,M) columns are supplied in the array Z; if RANGE = 'V', the exact value of M is not known in advance and an upper bound must be used. not me having to say "just use an upper bound" 😭 that's on you, bestie.

LDZ ⭐

LDZ is INTEGER — the leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', LDZ >= max(1,N).

read the constraints. love the constraints. 💜

WORK 🌈

WORK is COMPLEX*16 array, dimension (2*N).

RWORK 🌈

RWORK is DOUBLE PRECISION array, dimension (7*N).

IWORK 🌈

IWORK is INTEGER array, dimension (5*N).

(three lil scratchpads, no notes, just vibes 🫶)

IFAIL 🌸

IFAIL is INTEGER array, dimension (N).

if JOBZ = 'V', then if INFO = 0, the first M elements of IFAIL are zero. if INFO > 0, then IFAIL contains the indices of the eigenvectors that failed to converge.

if JOBZ = 'N', then IFAIL is not referenced.

the naughty list, essentially. 💀

INFO 👑

INFO is INTEGER:

  • = 0: successful exit ✨
  • < 0: if INFO = -i, the i-th argument had an illegal value 😭
  • > 0: ZPPTRF or ZHPEVX returned an error code:
    • <= N: if INFO = i, ZHPEVX failed to converge; i eigenvectors failed to converge. their indices are stored in array IFAIL.
    • > N: if INFO = N + i, for 1 <= i <= n, then the leading principal minor of order i of B is not positive. the factorization of B could not be completed and no eigenvalues or eigenvectors were computed.

like... that last one is a full stop. nothing computed. we go home. 💀

💜 Author 💜

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

(the whole squad, honestly, shoutout 🫶)

🎀 Contributors: 🎀

Mark Fahey, Department of Mathematics, Univ. of Kentucky, USA

thank you Mark, king. 👑

⭐ Definition ⭐

Definition at line 274 of file zhpgvx.f.

🌸 Author 🌸

Generated automatically by Doxygen for LAPACK from the source code.

like, she wasn't even hand-written. she was born this way. 💅

so yeah, that's ZHPGVX for you — LAPACK, Version 3.12.0, straight out of /home/abui...RC/zhpgvx.f(3). go forth and compute your generalized Hermitian-definite eigenproblems, bestie. no cap, you've got this. 🦋✨💖

📦 where this page comes from