complex16OTHEReigen(3)

📦

version 3.11.0 · 2 versions

3.11.0 · debian bookworm (latest)
3.10.0 · ubuntu jammy

💖 complex16OTHEReigen(3) — the LAPACK complex16 "Other Eigenvalue" saga 💖

okay so bestie, welcome to complex16OTHEReigen, a LAPACK manual page that's literally the group chat for every complex16 routine that does eigenvalues but isn't a standard ?ev / ?evd / ?evr situation. it's giving "the other ones" and honestly? iconic. no cap, there's a LOT here — so buckle up, we're going routine by routine, and I'm keeping every single detail because that's the whole vibe. 🫶

🌸 NAME 🌸

complex16OTHEReigen — complex16 Other Eigenvalue routines ✨

✨ SYNOPSIS ✨

🎀 Functions 🎀

here's the whole cast, bestie. every single one of these is a subroutine, and every signature is exactly what you'll type. no shortcuts, no renamed args, fr fr. 💅

zggglm — subroutine zggglm (N, M, P, A, LDA, B, LDB, D, X, Y, WORK, LWORK, INFO) — ZGGGLM
zhbev — subroutine zhbev (JOBZ, UPLO, N, KD, AB, LDAB, W, Z, LDZ, WORK, RWORK, INFO) — ZHBEV computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices
zhbev_2stage — subroutine zhbev_2stage (JOBZ, UPLO, N, KD, AB, LDAB, W, Z, LDZ, WORK, LWORK, RWORK, INFO) — ZHBEV_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices
zhbevd — subroutine zhbevd (JOBZ, UPLO, N, KD, AB, LDAB, W, Z, LDZ, WORK, LWORK, RWORK, LRWORK, IWORK, LIWORK, INFO) — ZHBEVD computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices
zhbevd_2stage — subroutine zhbevd_2stage (JOBZ, UPLO, N, KD, AB, LDAB, W, Z, LDZ, WORK, LWORK, RWORK, LRWORK, IWORK, LIWORK, INFO) — ZHBEVD_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices
zhbevx — subroutine zhbevx (JOBZ, RANGE, UPLO, N, KD, AB, LDAB, Q, LDQ, VL, VU, IL, IU, ABSTOL, M, W, Z, LDZ, WORK, RWORK, IWORK, IFAIL, INFO) — ZHBEVX computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices
zhbevx_2stage — subroutine zhbevx_2stage (JOBZ, RANGE, UPLO, N, KD, AB, LDAB, Q, LDQ, VL, VU, IL, IU, ABSTOL, M, W, Z, LDZ, WORK, LWORK, RWORK, IWORK, IFAIL, INFO) — ZHBEVX_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices
zhbgv — subroutine zhbgv (JOBZ, UPLO, N, KA, KB, AB, LDAB, BB, LDBB, W, Z, LDZ, WORK, RWORK, INFO) — ZHBGV
zhbgvd — subroutine zhbgvd (JOBZ, UPLO, N, KA, KB, AB, LDAB, BB, LDBB, W, Z, LDZ, WORK, LWORK, RWORK, LRWORK, IWORK, LIWORK, INFO) — ZHBGVD
zhbgvx — subroutine zhbgvx (JOBZ, RANGE, UPLO, N, KA, KB, AB, LDAB, BB, LDBB, Q, LDQ, VL, VU, IL, IU, ABSTOL, M, W, Z, LDZ, WORK, RWORK, IWORK, IFAIL, INFO) — ZHBGVX
zhpev — subroutine zhpev (JOBZ, UPLO, N, AP, W, Z, LDZ, WORK, RWORK, INFO) — ZHPEV computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices
zhpevd — subroutine zhpevd (JOBZ, UPLO, N, AP, W, Z, LDZ, WORK, LWORK, RWORK, LRWORK, IWORK, LIWORK, INFO) — ZHPEVD computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices
zhpevx — subroutine zhpevx (JOBZ, RANGE, UPLO, N, AP, VL, VU, IL, IU, ABSTOL, M, W, Z, LDZ, WORK, RWORK, IWORK, IFAIL, INFO) — ZHPEVX computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices
zhpgv — subroutine zhpgv (ITYPE, JOBZ, UPLO, N, AP, BP, W, Z, LDZ, WORK, RWORK, INFO) — ZHPGV
zhpgvd — subroutine zhpgvd (ITYPE, JOBZ, UPLO, N, AP, BP, W, Z, LDZ, WORK, LWORK, RWORK, LRWORK, IWORK, LIWORK, INFO) — ZHPGVD
zhpgvx — subroutine zhpgvx (ITYPE, JOBZ, RANGE, UPLO, N, AP, BP, VL, VU, IL, IU, ABSTOL, M, W, Z, LDZ, WORK, RWORK, IWORK, IFAIL, INFO) — ZHPGVX

🦋 Detailed Description 🦋

This is the group of complex16 Other Eigenvalue routines. that's the whole pitch bestie, and honestly it ate. 🍓

👑 Function Documentation 👑

🌟 subroutine zggglm 🌟

subroutine zggglm (integer N, integer M, integer P, complex*16, dimension( lda, * ) A, integer LDA, complex*16, dimension( ldb, * ) B, integer LDB, complex*16, dimension( * ) D, complex*16, dimension( * ) X, complex*16, dimension( * ) Y, complex*16, dimension( * ) WORK, integer LWORK, integer INFO)

ZGGGLM ✨

🎯 Purpose

ZGGGLM solves a general Gauss-Markov linear model (GLM) problem:

        minimize || y ||_2   subject to   d = A*x + B*y
            x

where A is an N-by-M matrix, B is an N-by-P matrix, and d is a
given N-vector. It is assumed that M <= N <= M+P, and

           rank(A) = M    and    rank( A B ) = N.

Under these assumptions, the constrained equation is always
consistent, and there is a unique solution x and a minimal 2-norm
solution y, which is obtained using a generalized QR factorization
of the matrices (A, B) given by

   A = Q*(R),   B = Q*T*Z.
         (0)

In particular, if matrix B is square nonsingular, then the problem
GLM is equivalent to the following weighted linear least squares
problem

             minimize || inv(B)*(d-A*x) ||_2
                 x

where inv(B) denotes the inverse of B.

🔧 Parameters

N — INTEGER. The number of rows of the matrices A and B. N >= 0.
M — INTEGER. The number of columns of the matrix A. 0 <= M <= N.
P — INTEGER. The number of columns of the matrix B. P >= N-M.
A — COMPLEX*16 array, dimension (LDA,M).
- On entry, the N-by-M matrix A.
- On exit, the upper triangular part of the array A contains the M-by-M upper triangular matrix R.
LDA — INTEGER. The leading dimension of the array A. LDA >= max(1,N).
B — COMPLEX*16 array, dimension (LDB,P).
- On entry, the N-by-P matrix B.
- On exit, if N <= P, the upper triangle of the subarray B(1:N,P-N+1:P) contains the N-by-N upper triangular matrix T; if N > P, the elements on and above the (N-P)th subdiagonal contain the N-by-P upper trapezoidal matrix T.
LDB — INTEGER. The leading dimension of the array B. LDB >= max(1,N).
D — COMPLEX*16 array, dimension (N).
- On entry, D is the left hand side of the GLM equation.
- On exit, D is destroyed. 💀 (yes really, it's gone)
X — COMPLEX*16 array, dimension (M).
Y — COMPLEX*16 array, dimension (P).
- On exit, X and Y are the solutions of the GLM problem. 🎉
WORK — COMPLEX*16 array, dimension (MAX(1,LWORK)).
- On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK — INTEGER. The dimension of the array WORK. LWORK >= max(1,N+M+P). For optimum performance, LWORK >= M+min(N,P)+max(N,P)*NB, where NB is an upper bound for the optimal blocksizes for ZGEQRF, ZGERQF, ZUNMQR and ZUNMRQ.
- 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.
INFO — INTEGER.
- = 0: successful exit. 🫶
- < 0: if INFO = -i, the i-th argument had an illegal value.
- = 1: the upper triangular factor R associated with A in the generalized QR factorization of the pair (A, B) is singular, so that rank(A) < M; the least squares solution could not be computed. 😭
- = 2: the bottom (N-M) by (N-M) part of the upper trapezoidal factor T associated with B in the generalized QR factorization of the pair (A, B) is singular, so that rank( A B ) < N; the least squares solution could not be computed. 😭

✍️ Author

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

🌟 subroutine zhbev 🌟

subroutine zhbev (character JOBZ, character UPLO, integer N, integer KD, complex*16, dimension( ldab, * ) AB, integer LDAB, double precision, dimension( * ) W, complex*16, dimension( ldz, * ) Z, integer LDZ, complex*16, dimension( * ) WORK, double precision, dimension( * ) RWORK, integer INFO)

ZHBEV computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices 💜

🎯 Purpose

ZHBEV computes all the eigenvalues and, optionally, eigenvectors of
a complex Hermitian band matrix A.

🔧 Parameters

JOBZ — CHARACTER*1.
- = 'N': Compute eigenvalues only;
- = 'V': Compute eigenvalues and eigenvectors.
UPLO — CHARACTER*1.
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — INTEGER. The order of the matrix A. N >= 0.
KD — INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
AB — COMPLEX*16 array, dimension (LDAB, N).
- On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:
 - if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
 - if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).
- On exit, AB is overwritten by values generated during the reduction to tridiagonal form. If UPLO = 'U', the first superdiagonal and the diagonal of the tridiagonal matrix T are returned in rows KD and KD+1 of AB, and if UPLO = 'L', the diagonal and first subdiagonal of T are returned in the first two rows of AB.
LDAB — INTEGER. The leading dimension of the array AB. LDAB >= KD + 1.
W — DOUBLE PRECISION array, dimension (N). If INFO = 0, the eigenvalues in ascending order. ⭐
Z — COMPLEX*16 array, dimension (LDZ, N).
- If JOBZ = 'V', then if INFO = 0, Z contains the orthonormal eigenvectors of the matrix A, with the i-th column of Z holding the eigenvector associated with W(i).
- If JOBZ = 'N', then Z is not referenced. 🙈
LDZ — INTEGER. The leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', LDZ >= max(1,N).
WORK — COMPLEX*16 array, dimension (N).
RWORK — DOUBLE PRECISION array, dimension (max(1,3*N-2)).
INFO
INFO is INTEGER
- = 0: successful exit. slay, no notes 💅
- < 0: if INFO = -i, the i-th argument had an illegal value — so like, argument number i is the one acting up, bestie
- > 0: if INFO = i, the algorithm failed to converge; i off-diagonal elements of an intermediate tridiagonal form did not converge to zero. it just would not lock in 😭

👑 Author 👑

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

🌈 `subroutine zhbev_2stage (character JOBZ, character UPLO, integer N, integer KD, complex16, dimension( ldab, ) AB, integer LDAB, double precision, dimension( * ) W, complex16, dimension( ldz, ) Z, integer LDZ, complex16, dimension( ) WORK, integer LWORK, double precision, dimension( * ) RWORK, integer INFO)`

ZHBEV_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices

🎀 Purpose 🎀

ZHBEV_2STAGE computes all the eigenvalues and, optionally, eigenvectors of a complex Hermitian band matrix A using the 2stage technique for the reduction to tridiagonal. it's giving ✨efficient✨, fr fr.

💖 Parameters 💖

JOBZ

JOBZ is CHARACTER*1

= 'N': Compute eigenvalues only;
= 'V': Compute eigenvalues and eigenvectors. Not available in this release. 🫠 (like, it's on the vision board, not in the build)

UPLO

UPLO is CHARACTER*1

= 'U': Upper triangle of A is stored;
= 'L': Lower triangle of A is stored.

N

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

KD

KD is INTEGER The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.

AB

AB is COMPLEX*16 array, dimension (LDAB, N) On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:

if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+kd).

On exit, AB is overwritten by values generated during the reduction to tridiagonal form. If UPLO = 'U', the first superdiagonal and the diagonal of the tridiagonal matrix T are returned in rows KD and KD+1 of AB, and if UPLO = 'L', the diagonal and first subdiagonal of T are returned in the first two rows of AB. so yeah, your input gets a whole glow-up in place 💫

LDAB

LDAB is INTEGER The leading dimension of the array AB. LDAB >= KD + 1.

W

W is DOUBLE PRECISION array, dimension (N) If INFO = 0, the eigenvalues in ascending order. sorted, organized, main character behavior 🍓

Z

Z is COMPLEX*16 array, dimension (LDZ, N) If JOBZ = 'V', then if INFO = 0, Z contains the orthonormal eigenvectors of the matrix A, with the i-th column of Z holding the eigenvector associated with W(i). If JOBZ = 'N', then Z is not referenced. ghosted, literally not even looked at 🙈

LDZ

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

WORK

WORK is COMPLEX*16 array, dimension LWORK On exit, if INFO = 0, WORK(1) returns the optimal LWORK.

LWORK

LWORK is INTEGER The length of the array WORK. LWORK >= 1, when N <= 1; otherwise

If JOBZ = 'N' and N > 1, LWORK must be queried.
                         LWORK = MAX(1, dimension) where
                         dimension = (2KD+1)*N + KD*NTHREADS
                         where KD is the size of the band.
                         NTHREADS is the number of threads used when
                         openMP compilation is enabled, otherwise =1.
If JOBZ = 'V' and N > 1, LWORK must be queried. Not yet available.

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA. it's just peeking, not committing 💅

RWORK

RWORK is DOUBLE PRECISION array, dimension (max(1,3*N-2))

INFO

INFO is INTEGER

= 0: successful exit. 🎉
< 0: if INFO = -i, the i-th argument had an illegal value.
> 0: if INFO = i, the algorithm failed to converge; i off-diagonal elements of an intermediate tridiagonal form did not converge to zero. the drama of it all 😭

👑 Author 👑

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

📚 Further Details: 📚

All details about the 2stage techniques are available in:

Azzam Haidar, Hatem Ltaief, and Jack Dongarra. Parallel reduction to condensed forms for symmetric eigenvalue problems using aggregated fine-grained and memory-aware kernels. In Proceedings of 2011 International Conference for High Performance Computing, Networking, Storage and Analysis (SC '11), New York, NY, USA, Article 8 , 11 pages. http://doi.acm.org/10.1145/2063384.2063394

A. Haidar, J. Kurzak, P. Luszczek, 2013. An improved parallel singular value algorithm and its implementation for multicore hardware, In Proceedings of 2013 International Conference for High Performance Computing, Networking, Storage and Analysis (SC '13). Denver, Colorado, USA, 2013. Article 90, 12 pages. http://doi.acm.org/10.1145/2503210.2503292

A. Haidar, R. Solca, S. Tomov, T. Schulthess and J. Dongarra. A novel hybrid CPU-GPU generalized eigensolver for electronic structure calculations based on fine-grained memory aware tasks. International Journal of High Performance Computing Applications. Volume 28 Issue 2, Pages 196-209, May 2014. http://hpc.sagepub.com/content/28/2/196

🦋 `subroutine zhbevd (character JOBZ, character UPLO, integer N, integer KD, complex16, dimension( ldab, ) AB, integer LDAB, double precision, dimension( * ) W, complex16, dimension( ldz, ) Z, integer LDZ, complex16, dimension( ) WORK, integer LWORK, double precision, dimension( * ) RWORK, integer LRWORK, integer, dimension( * ) IWORK, integer LIWORK, integer INFO)`

ZHBEVD computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices

🎀 Purpose 🎀

ZHBEVD computes all the eigenvalues and, optionally, eigenvectors of a complex Hermitian band matrix A. If eigenvectors are desired, it uses a divide and conquer algorithm. it's giving strategy, periodt.

The divide and conquer algorithm makes very mild assumptions about floating point arithmetic. It will work on machines with a guard digit in add/subtract, or on those binary machines without guard digits which subtract like the Cray X-MP, Cray Y-MP, Cray C-90, or Cray-2. It could conceivably fail on hexadecimal or decimal machines without guard digits, but we know of none. so like... probably fine? iconic confidence tbh 🧚

💖 Parameters 💖

JOBZ

JOBZ is CHARACTER*1

= 'N': Compute eigenvalues only;
= 'V': Compute eigenvalues and eigenvectors.

UPLO

UPLO is CHARACTER*1

= 'U': Upper triangle of A is stored;
= 'L': Lower triangle of A is stored.

N

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

KD

KD is INTEGER The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.

AB

if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+kd).

LDAB

LDAB is INTEGER The leading dimension of the array AB. LDAB >= KD + 1.

W

W is DOUBLE PRECISION array, dimension (N) If INFO = 0, the eigenvalues in ascending order. ascending, as it should be 💅

Z

LDZ

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

WORK

WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.

LWORK

LWORK is INTEGER The dimension of the array WORK.

If N <= 1,               LWORK must be at least 1.
If JOBZ = 'N' and N > 1, LWORK must be at least N.
If JOBZ = 'V' and N > 1, LWORK must be at least 2*N**2.

RWORK

RWORK is DOUBLE PRECISION array, dimension (LRWORK) On exit, if INFO = 0, RWORK(1) returns the optimal LRWORK.

LRWORK
LRWORK is INTEGER — the dimension of array RWORK, so like, it's gotta be big enough for the vibes 🫶
- If N <= 1, then LRWORK must be at least 1.
- If JOBZ = 'N' and N > 1, LRWORK must be at least N.
- If JOBZ = 'V' and N > 1, LRWORK must be at least 1 + 5*N + 2*N**2.

If LRWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA. (so like, it ghosts the error messages, iconic honestly 💅)

IWORK — IWORK is INTEGER array, dimension (MAX(1,LIWORK)). On exit, if INFO = 0, IWORK(1) returns the optimal LIWORK. she's reporting back bestie 💖
LIWORK is INTEGER — the dimension of array IWORK.
- If JOBZ = 'N' or N <= 1, LIWORK must be at least 1.
- If JOBZ = 'V' and N > 1, LIWORK must be at least 3 + 5*N.

If LIWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA. ✨

INFO is INTEGER — the moment of truth, the vibe check at the end 🦋
- = 0: successful exit. slay 💅
- < 0: if INFO = -i, the i-th argument had an illegal value. someone fumbled 🙈
- > 0: if INFO = i, the algorithm failed to converge; i off-diagonal elements of an intermediate tridiagonal form did not converge to zero. it's giving "not me crying in floating point" 😭

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

subroutine `zhbevd_2stage`

subroutine zhbevd_2stage (character JOBZ, character UPLO, integer N, integer
    KD, complex*16, dimension( ldab, * ) AB, integer LDAB, double precision,
    dimension( * ) W, complex*16, dimension( ldz, * ) Z, integer LDZ,
    complex*16, dimension( * ) WORK, integer LWORK, double precision,
    dimension( * ) RWORK, integer LRWORK, integer, dimension( * ) IWORK,
    integer LIWORK, integer INFO)

ZHBEVD_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices — no cap, that's the whole job description 🌈

Purpose:

ZHBEVD_2STAGE computes all the eigenvalues and, optionally, eigenvectors of a complex Hermitian band matrix A using the 2stage technique for the reduction to tridiagonal. If eigenvectors are desired, it uses a divide and conquer algorithm. queen behaviour honestly 👑

The divide and conquer algorithm makes very mild assumptions about floating point arithmetic. It will work on machines with a guard digit in add/subtract, or on those binary machines without guard digits which subtract like the Cray X-MP, Cray Y-MP, Cray C-90, or Cray-2. It could conceivably fail on hexadecimal or decimal machines without guard digits, but we know of none. (so like, it could fail, but nobody's ever seen it happen — she's resilient fr fr 💪)

Parameters

JOBZ is CHARACTER*1 — pick your destiny bestie:
- = 'N': Compute eigenvalues only;
- = 'V': Compute eigenvalues and eigenvectors. Not available in this release. (yeah, that door is locked in this release, no cap 🚪🔒)
UPLO is CHARACTER*1 — which triangle are we even looking at:
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N is INTEGER — the order of the matrix A. N >= 0.
KD is INTEGER — the number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
AB is COMPLEX*16 array, dimension (LDAB, N) — okay so on entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:

if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+kd).

On exit, AB is overwritten by values generated during the reduction to tridiagonal form. If UPLO = 'U', the first superdiagonal and the diagonal of the tridiagonal matrix T are returned in rows KD and KD+1 of AB, and if UPLO = 'L', the diagonal and first subdiagonal of T are returned in the first two rows of AB. (yes she will be overwriting your data, she said what she said 💀)

LDAB is INTEGER — the leading dimension of the array AB. LDAB >= KD + 1.
W is DOUBLE PRECISION array, dimension (N) — if INFO = 0, the eigenvalues in ascending order. all lined up, neat and pretty ✨
Z is COMPLEX*16 array, dimension (LDZ, N) — if JOBZ = 'V', then if INFO = 0, Z contains the orthonormal eigenvectors of the matrix A, with the i-th column of Z holding the eigenvector associated with W(i). If JOBZ = 'N', then Z is not referenced. (she's not even in the group chat if you pick 'N' 🙈)
LDZ is INTEGER — the leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', LDZ >= max(1,N).
WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)) — on exit, if INFO = 0, WORK(1) returns the optimal LWORK.
LWORK is INTEGER — the length of the array WORK. LWORK >= 1, when N <= 1; otherwise:
- If JOBZ = 'N' and N > 1, LWORK must be queried.

LWORK = MAX(1, dimension) where
dimension = (2KD+1)*N + KD*NTHREADS
where KD is the size of the band.
NTHREADS is the number of threads used when
openMP compilation is enabled, otherwise =1.

If JOBZ = 'V' and N > 1, LWORK must be queried. Not yet available. (coming eventually, she promises 🎀)

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA.

RWORK is DOUBLE PRECISION array, dimension (LRWORK) — on exit, if INFO = 0, RWORK(1) returns the optimal LRWORK.
LRWORK is INTEGER — the dimension of array RWORK.
- If N <= 1, LRWORK must be at least 1.
- If JOBZ = 'N' and N > 1, LRWORK must be at least N.
- If JOBZ = 'V' and N > 1, LRWORK must be at least 1 + 5*N + 2*N**2.

If LRWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA. 💖

IWORK is INTEGER array, dimension (MAX(1,LIWORK)) — on exit, if INFO = 0, IWORK(1) returns the optimal LIWORK.
LIWORK is INTEGER — the dimension of array IWORK.
- If JOBZ = 'N' or N <= 1, LIWORK must be at least 1.
- If JOBZ = 'V' and N > 1, LIWORK must be at least 3 + 5*N.

If LIWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA. ✨

INFO is INTEGER — the final verdict:
- = 0: successful exit. we ate 🍓
- < 0: if INFO = -i, the i-th argument had an illegal value.
- > 0: if INFO = i, the algorithm failed to converge; i off-diagonal elements of an intermediate tridiagonal form did not converge to zero. 😭

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Further Details:

All details about the 2stage techniques are available in — okay bestie, citation time, she's academic AND cute 📚✨

subroutine `zhbevx`

subroutine zhbevx (character JOBZ, character RANGE, character UPLO, integer
    N, integer KD, complex*16, dimension( ldab, * ) AB, integer LDAB,
    complex*16, dimension( ldq, * ) Q, integer LDQ, 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)

ZHBEVX computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices 🌸

Purpose:

okay so like, buckle up buttercup, the details for this one are right up next 💜

...ZHBEVX is that girl: she computes selected eigenvalues and, if you want, eigenvectors too, of a complex Hermitian band matrix A. You can pick your faves either by a range of values or a range of indices. Choose your fighter. 💅

✨ Parameters ✨

JOBZ — CHARACTER*1, bestie, pick one:
- = 'N': compute eigenvalues only;
- = 'V': compute eigenvalues and eigenvectors.
RANGE — CHARACTER*1, the vibe selector:
- = '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.
UPLO — CHARACTER*1, which triangle are we even looking at:
- = 'U': upper triangle of A is stored;
- = 'L': lower triangle of A is stored.
N — INTEGER. The order of the matrix A. N >= 0. periodt.
KD — INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
AB — COMPLEX*16 array, dimension (LDAB, N). On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:
- if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
- if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).

On exit, AB is overwritten by values generated during the reduction to tridiagonal form. (Yeah she will touch your array, that's just how it is 🙈)

LDAB — INTEGER. The leading dimension of the array AB. LDAB >= KD + 1.
Q — COMPLEX*16 array, dimension (LDQ, N).
- If JOBZ = 'V', the N-by-N unitary matrix used in the reduction to tridiagonal form.
- If JOBZ = 'N', the array Q is not referenced. (she's off-duty, not even looking 👑)
LDQ — INTEGER. The leading dimension of the array Q. If JOBZ = 'V', then LDQ >= max(1,N).
VL — 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 — 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'.
IL — 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 — 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 — 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 AB 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'). (ngl this is the glow-up you want ✨)

See 'Computing Small Singular Values of Bidiagonal Matrices with Guaranteed High Relative Accuracy,' by Demmel and Kahan, LAPACK Working Note #3.

M — INTEGER. The total number of eigenvalues found. 0 <= M <= N. If RANGE = 'A', M = N, and if RANGE = 'I', M = IU-IL+1.
W — DOUBLE PRECISION array, dimension (N). The first M elements contain the selected eigenvalues in ascending order. 💖
Z — COMPLEX*16 array, dimension (LDZ, max(1,M)). 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). 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. If JOBZ = 'N', then Z is not referenced.

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. (plan ahead bestie, she's not gonna guess for you 😭)

LDZ — INTEGER. The leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', LDZ >= max(1,N).
WORK — COMPLEX*16 array, dimension (N).
RWORK — DOUBLE PRECISION array, dimension (7*N).
IWORK — INTEGER array, dimension (5*N).
IFAIL — 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.
INFO — INTEGER.
- = 0: successful exit 🎉
- < 0: if INFO = -i, the i-th argument had an illegal value
- > 0: if INFO = i, then i eigenvectors failed to converge. Their indices are stored in array IFAIL.

🦋 Author 🦋

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌸 subroutine zhbevx_2stage 🌸

subroutine zhbevx_2stage (character JOBZ, character RANGE, character UPLO,
    integer N, integer KD, complex*16, dimension( ldab, * ) AB, integer
    LDAB, complex*16, dimension( ldq, * ) Q, integer LDQ, 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,
    integer LWORK, double precision, dimension( * ) RWORK, integer,
    dimension( * ) IWORK, integer, dimension( * ) IFAIL, integer INFO)

ZHBEVX_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices. (yes the name is a whole mouthful, we love her anyway 💜)

✨ Purpose ✨

ZHBEVX_2STAGE computes selected eigenvalues and, optionally, eigenvectors of a complex Hermitian band matrix A using the 2stage technique for the reduction to tridiagonal. Eigenvalues and eigenvectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues.

💅 Parameters 💅

JOBZ — CHARACTER*1.
- = 'N': Compute eigenvalues only;
- = 'V': Compute eigenvalues and eigenvectors.

Not available in this release. (ik, devastating. read the room bestie 😭)

RANGE — 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.
UPLO — CHARACTER*1.
- = 'U': upper triangle of A is stored;
- = 'L': lower triangle of A is stored.
N — INTEGER. The order of the matrix A. N >= 0.
KD — INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
AB — COMPLEX*16 array, dimension (LDAB, N). On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:
- if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
- if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).

On exit, AB is overwritten by values generated during the reduction to tridiagonal form.

LDAB — INTEGER. The leading dimension of the array AB. LDAB >= KD + 1.
Q — COMPLEX*16 array, dimension (LDQ, N).
- If JOBZ = 'V', the N-by-N unitary matrix used in the reduction to tridiagonal form.
- If JOBZ = 'N', the array Q is not referenced.
LDQ — INTEGER. The leading dimension of the array Q. If JOBZ = 'V', then LDQ >= max(1,N).
VL — 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 — 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'.
IL — 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 — bestie, IU is INTEGER ✨ If RANGE='I', it's the index of the largest eigenvalue you want back. Rules of the road: 1 <= IL <= IU <= N if N > 0; and IL = 1 plus IU = 0 when N = 0. It is not referenced if RANGE = 'A' or 'V' — so don't stress about it then, she's off duty 💅
ABSTOL — ABSTOL is DOUBLE PRECISION 🎯 It's the absolute error tolerance for the eigenvalues. An approximate eigenvalue gets accepted as converged when it's determined to lie in an interval [a,b] whose width is 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| gets used in its place, where |T| is the 1-norm of the tridiagonal matrix you get by reducing AB to tridiagonal form. Lowkey important: eigenvalues are computed most accurately when ABSTOL is set to twice the underflow threshold 2*DLAMCH('S'), not zero 🚨 If this routine comes back with INFO>0 — meaning some eigenvectors did not converge — try setting ABSTOL to 2*DLAMCH('S'). And if you wanna go deep: see 'Computing Small Singular Values of Bidiagonal Matrices with Guaranteed High Relative Accuracy,' by Demmel and Kahan, LAPACK Working Note #3 📚

M — M is INTEGER 🌸 The total number of eigenvalues found. 0 <= M <= N. If RANGE = 'A', then M = N, and if RANGE = 'I', then M = IU-IL+1. Math girlies stay winning 💖
W — W is DOUBLE PRECISION array, dimension (N) ⭐ The first M elements contain the selected eigenvalues in ascending order. Sorted and slaying, as she should 👑
Z — Z is COMPLEX*16 array, dimension (LDZ, max(1,M)) 🦋 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). 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 😭 If JOBZ = 'N', then Z is not referenced at all, she's not even invited. Note: you 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 so you gotta use an upper bound 🙈
LDZ — LDZ is INTEGER 💫 The leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', LDZ >= max(1,N).
WORK — WORK is COMPLEX*16 array, dimension (LWORK) 🎀
LWORK — LWORK is INTEGER 🌈 The length of the array WORK. LWORK >= 1, when N <= 1; otherwise:
- If JOBZ = 'N' and N > 1, LWORK must be queried.

LWORK = MAX(1, dimension) where
dimension = (2KD+1)*N + KD*NTHREADS
where KD is the size of the band.
NTHREADS is the number of threads used when
openMP compilation is enabled, otherwise =1.

If JOBZ = 'V' and N > 1, LWORK must be queried. Not yet available. 💀

RWORK — RWORK is DOUBLE PRECISION array, dimension (7*N) 🌸
IWORK — IWORK is INTEGER array, dimension (5*N) 🧚
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. She's the receipts keeper fr fr 🧾
INFO — INFO is INTEGER 📣
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value 🙅
- > 0: if INFO = i, then i eigenvectors failed to converge. Their indices are stored in array IFAIL 😭

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details: 🔍

All details about the 2stage techniques are available in:

Azzam Haidar, Hatem Ltaief, and Jack Dongarra.
Parallel reduction to condensed forms for symmetric eigenvalue problems
using aggregated fine-grained and memory-aware kernels. In Proceedings
of 2011 International Conference for High Performance Computing,
Networking, Storage and Analysis (SC '11), New York, NY, USA,
Article 8 , 11 pages.
http://doi.acm.org/10.1145/2063384.2063394

A. Haidar, J. Kurzak, P. Luszczek, 2013.
An improved parallel singular value algorithm and its implementation
for multicore hardware, In Proceedings of 2013 International Conference
for High Performance Computing, Networking, Storage and Analysis (SC '13).
Denver, Colorado, USA, 2013.
Article 90, 12 pages.
http://doi.acm.org/10.1145/2503210.2503292

A. Haidar, R. Solca, S. Tomov, T. Schulthess and J. Dongarra.
A novel hybrid CPU-GPU generalized eigensolver for electronic structure
calculations based on fine-grained memory aware tasks.
International Journal of High Performance Computing Applications.
Volume 28 Issue 2, Pages 196-209, May 2014.
http://hpc.sagepub.com/content/28/2/196

Citation queen behaviour, we love to see it 📚💖

🦋 subroutine zhbgv 🦋

subroutine zhbgv (character JOBZ, character UPLO, integer N, integer KA,
    integer KB, complex*16, dimension( ldab, * ) AB, integer LDAB,
    complex*16, dimension( ldbb, * ) BB, integer LDBB, double precision,
    dimension( * ) W, complex*16, dimension( ldz, * ) Z, integer LDZ,
    complex*16, dimension( * ) WORK, double precision, dimension( * ) RWORK,
    integer INFO)

ZHBGV

✨ Purpose: ✨

ZHBGV computes all the eigenvalues, and optionally, the eigenvectors of a complex generalized Hermitian-definite banded eigenproblem, of the form A*x=(lambda)*B*x. Here A and B are assumed to be Hermitian and banded, and B is also positive definite. No cap, she does the whole glow-up on a banded problem 🫶

🎀 Parameters 🎀

JOBZ — JOBZ is CHARACTER*1 💫
- = 'N': Compute eigenvalues only;
- = 'V': Compute eigenvalues and eigenvectors.
UPLO — UPLO is CHARACTER*1 🌸
- = 'U': Upper triangles of A and B are stored;
- = 'L': Lower triangles of A and B are stored.
N — N is INTEGER ⭐ The order of the matrices A and B. N >= 0.
KA — KA is INTEGER 🦋 The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KA >= 0.
KB — KB is INTEGER 🌈 The number of superdiagonals of the matrix B if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KB >= 0.
AB — AB is COMPLEX*16 array, dimension (LDAB, N) 💖 On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first ka+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:

if UPLO = 'U', AB(ka+1+i-j,j) = A(i,j) for max(1,j-ka)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+ka).

On exit, the contents of AB are destroyed 💀 she did what she had to do.

LDAB — LDAB is INTEGER ✨ The leading dimension of the array AB. LDAB >= KA+1.
BB — BB is COMPLEX*16 array, dimension (LDBB, N) 🧚 On entry, the upper or lower triangle of the Hermitian band matrix B, stored in the first kb+1 rows of the array. The j-th column of B is stored in the j-th column of the array BB as follows:

if UPLO = 'U', BB(kb+1+i-j,j) = B(i,j) for max(1,j-kb)<=i<=j;
if UPLO = 'L', BB(1+i-j,j)    = B(i,j) for j<=i<=min(n,j+kb).

On exit, the factor S from the split Cholesky factorization B = S**H*S, as returned by ZPBSTF 👑

LDBB — LDBB is INTEGER 💜 The leading dimension of the array BB. LDBB >= KB+1.
W — W is DOUBLE PRECISION array, dimension (N) ⭐ If INFO = 0, the eigenvalues in ascending order. Sorted, ascending, thriving 📈
Z — Z is COMPLEX*16 array, dimension (LDZ, N) 🦋 If JOBZ = 'V', then if INFO = 0, Z contains the matrix Z of eigenvectors, with the i-th column of Z holding the eigenvector associated with W(i). The eigenvectors are normalized so that Z**H*B*Z = I. If JOBZ = 'N', then Z is not referenced — she's simply not in the group chat 💅
LDZ — LDZ is INTEGER 🌸 The leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', LDZ >= N.
WORK — WORK is COMPLEX*16 array, dimension (N) 🎀
RWORK — RWORK is DOUBLE PRECISION array, dimension (3*N) 🌈
INFO — INFO is INTEGER 📣
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value 🙅
- > 0: if INFO = i, and i is:
 - <= N: the algorithm failed to converge: i off-diagonal elements of an intermediate tridiagonal form did not converge to zero 😭
 - > N: if INFO = N + i, for 1 <= i <= N, then ZPBSTF returned INFO = i: B is not positive definite. The factorization of B could not be completed and no eigenvalues or eigenvectors were computed. Devastating. Nothing was served 💀

💖 Author 💖

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

`subroutine zhbgvd`

subroutine zhbgvd (character JOBZ, character UPLO, integer N, integer KA,
    integer KB, complex*16, dimension( ldab, * ) AB, integer LDAB,
    complex*16, dimension( ldbb, * ) BB, integer LDBB, double precision,
    dimension( * ) W, complex*16, dimension( ldz, * ) Z, integer LDZ,
    complex*16, dimension( * ) WORK, integer LWORK, double precision,
    dimension( * ) RWORK, integer LRWORK, integer, dimension( * ) IWORK,
    integer LIWORK, integer INFO)
    ZHBGVD

Purpose ✨

ZHBGVD computes all the eigenvalues — and, if you want them, the eigenvectors too — of a complex generalized Hermitian-definite banded eigenproblem, bestie. The form is:

A*x=(lambda)*B*x

Here A and B are assumed to be Hermitian and banded, and B is also positive definite. If eigenvectors are desired, it uses a divide and conquer algorithm. 👑

The divide and conquer algorithm makes very mild assumptions about floating point arithmetic. It will work on machines with a guard digit in add/subtract, or on those binary machines without guard digits which subtract like the Cray X-MP, Cray Y-MP, Cray C-90, or Cray-2. It could conceivably fail on hexadecimal or decimal machines without guard digits, but we know of none. (no cap, that's just what the docs say 💀)

Parameters

JOBZ

JOBZ is CHARACTER*1, so pick your vibe:

'N': Compute eigenvalues only;
'V': Compute eigenvalues and eigenvectors.

UPLO

UPLO is CHARACTER*1 — which triangle are we even using, bestie:

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

N

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

KA

KA is INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KA >= 0.

KB

KB is INTEGER. The number of superdiagonals of the matrix B if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KB >= 0.

AB

AB is COMPLEX*16 array, dimension (LDAB, N). On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first ka+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:

if UPLO = 'U', AB(ka+1+i-j,j) = A(i,j) for max(1,j-ka)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+ka).

On exit, the contents of AB are destroyed. 💀

LDAB

LDAB is INTEGER. The leading dimension of the array AB. LDAB >= KA+1.

BB

BB is COMPLEX*16 array, dimension (LDBB, N). On entry, the upper or lower triangle of the Hermitian band matrix B, stored in the first kb+1 rows of the array. The j-th column of B is stored in the j-th column of the array BB as follows:

if UPLO = 'U', BB(kb+1+i-j,j) = B(i,j) for max(1,j-kb)<=i<=j;
if UPLO = 'L', BB(1+i-j,j)    = B(i,j) for j<=i<=min(n,j+kb).

On exit, the factor S from the split Cholesky factorization B = S**H*S, as returned by ZPBSTF.

LDBB

LDBB is INTEGER. The leading dimension of the array BB. LDBB >= KB+1.

W

W is DOUBLE PRECISION array, dimension (N). If INFO = 0, the eigenvalues in ascending order. ✨

Z

Z is COMPLEX*16 array, dimension (LDZ, N). If JOBZ = 'V', then if INFO = 0, Z contains the matrix Z of eigenvectors, with the i-th column of Z holding the eigenvector associated with W(i). The eigenvectors are normalized so that Z**H*B*Z = I. If JOBZ = 'N', then Z is not referenced.

LDZ

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

WORK

WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO=0, WORK(1) returns the optimal LWORK.

LWORK

LWORK is INTEGER. The dimension of the array WORK.

If N <= 1,               LWORK >= 1.
If JOBZ = 'N' and N > 1, LWORK >= N.
If JOBZ = 'V' and N > 1, LWORK >= 2*N**2.

If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA. 🫶

RWORK

RWORK is DOUBLE PRECISION array, dimension (MAX(1,LRWORK)). On exit, if INFO=0, RWORK(1) returns the optimal LRWORK.

LRWORK

LRWORK is INTEGER. The dimension of array RWORK.

If N <= 1,               LRWORK >= 1.
If JOBZ = 'N' and N > 1, LRWORK >= N.
If JOBZ = 'V' and N > 1, LRWORK >= 1 + 5*N + 2*N**2.

If LRWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA.

IWORK

IWORK is INTEGER array, dimension (MAX(1,LIWORK)). On exit, if INFO=0, IWORK(1) returns the optimal LIWORK.

LIWORK

LIWORK is INTEGER. The dimension of array IWORK.

If JOBZ = 'N' or N <= 1, LIWORK >= 1.
If JOBZ = 'V' and N > 1, LIWORK >= 3 + 5*N.

If LIWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA.

INFO

INFO is INTEGER:

= 0: successful exit 🎉
< 0: if INFO = -i, the i-th argument had an illegal value
> 0: if INFO = i, and i is:
- <= N: the algorithm failed to converge: i off-diagonal elements of an intermediate tridiagonal form did not converge to zero;
- > N: if INFO = N + i, for 1 <= i <= N, then ZPBSTF returned INFO = i: B is not positive definite. The factorization of B could not be completed and no eigenvalues or eigenvectors were computed. (this one hurts, bestie 😭)

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Contributors:

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

`subroutine zhbgvx`

subroutine zhbgvx (character JOBZ, character RANGE, character UPLO, integer
    N, integer KA, integer KB, complex*16, dimension( ldab, * ) AB, integer
    LDAB, complex*16, dimension( ldbb, * ) BB, integer LDBB, complex*16,
    dimension( ldq, * ) Q, integer LDQ, 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)
    ZHBGVX

Purpose 🌈

ZHBGVX computes all the eigenvalues, and optionally, the eigenvectors of a complex generalized Hermitian-definite banded eigenproblem, of the form:

A*x=(lambda)*B*x

Here A and B are assumed to be Hermitian and banded, and B is also positive definite. And the iconic part: eigenvalues and eigenvectors can be selected by specifying either all eigenvalues, a range of values or a range of indices for the desired eigenvalues. Choose your own adventure, fr fr. 🦋

Parameters

JOBZ

JOBZ is CHARACTER*1:

'N': Compute eigenvalues only;
'V': Compute eigenvalues and 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.

UPLO

UPLO is CHARACTER*1:

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

N

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

KA

KA is INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KA >= 0.

KB

KB is INTEGER. The number of superdiagonals of the matrix B if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KB >= 0.

AB

if UPLO = 'U', AB(ka+1+i-j,j) = A(i,j) for max(1,j-ka)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+ka).

On exit, the contents of AB are destroyed. 💀

LDAB

LDAB is INTEGER. The leading dimension of the array AB. LDAB >= KA+1.

BB

if UPLO = 'U', BB(kb+1+i-j,j) = B(i,j) for max(1,j-kb)<=i<=j;
if UPLO = 'L', BB(1+i-j,j)    = B(i,j) for j<=i<=min(n,j+kb).

On exit, the factor S from the split Cholesky factorization B = S**H*S, as returned by ZPBSTF.

LDBB

LDBB is INTEGER. The leading dimension of the array BB. LDBB >= KB+1.

Q

okay so still on Q, and here's the rest of the tea 🫖 — this one's a COMPLEX*16 array, dimension (LDQ, N).

If JOBZ = 'V', it's the n-by-n matrix used in the reduction of A*x = (lambda)*B*x to standard form, i.e. C*x = (lambda)*x, and consequently C to tridiagonal form.
If JOBZ = 'N', the array Q is not referenced at all. she's off duty, respect her privacy 💅
LDQ — LDQ is INTEGER, the leading dimension of the array Q. If JOBZ = 'N', then LDQ >= 1. If JOBZ = 'V', then LDQ >= max(1,N). get this wrong and it's over bestie
VL — VL is DOUBLE PRECISION. If RANGE='V', this is 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', this is the upper bound of the interval to be searched for eigenvalues. VL < VU. Not referenced if RANGE = 'A' or 'I'.
IL — IL is INTEGER. If RANGE='I', it's 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', it's 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 gets accepted as converged when it's 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| gets used in its place, where |T| is the 1-norm of the tridiagonal matrix obtained by reducing AP to tridiagonal form.

Eigenvalues get computed most accurately when ABSTOL is set to twice the underflow threshold 2*DLAMCH('S'), not zero. And listen — if this routine comes back with INFO>0, meaning some eigenvectors did not converge, try setting ABSTOL to 2*DLAMCH('S'). that's the glow-up fix ✨

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. she's counting for you, say thank you 🫶
W — W is DOUBLE PRECISION array, dimension (N). If INFO = 0, these are the eigenvalues in ascending order. sorted queen behavior
Z — Z is COMPLEX*16 array, dimension (LDZ, N). If JOBZ = 'V', then if INFO = 0, Z contains the matrix Z of eigenvectors, with the i-th column of Z holding the eigenvector associated with W(i). The eigenvectors are normalized so that Z**H*B*Z = I. If JOBZ = 'N', then Z is not referenced. normalized to the identity, as she should be 💅
LDZ — LDZ is INTEGER, the leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', LDZ >= N.
WORK — WORK is COMPLEX*16 array, dimension (N).
RWORK — RWORK is DOUBLE PRECISION array, dimension (7*N).
IWORK — IWORK is INTEGER array, dimension (5*N).
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.
INFO — INFO is INTEGER

= 0:  successful exit
< 0:  if INFO = -i, the i-th argument had an illegal value
> 0:  if INFO = i, and i is:
   <= N:  then i eigenvectors failed to converge.  Their
          indices are stored in array IFAIL.
   > N:   if INFO = N + i, for 1 <= i <= N, then ZPBSTF
          returned INFO = i: B is not positive definite.
          The factorization of B could not be completed and
          no eigenvalues or eigenvectors were computed.

INFO <= N means some eigenvectors ghosted you and their names are in IFAIL. INFO > N means ZPBSTF said B is not positive definite and literally nothing got computed. devastating, but at least you know why 😭

🌸 Author 🌸

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

💜 Contributors 💜

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

👑 subroutine zhpev (character JOBZ, character UPLO, integer N, complex16, dimension( ) AP, double precision, dimension( * ) W, complex16, dimension( ldz, ) Z, integer LDZ, complex16, dimension( ) WORK, double precision, dimension( * ) RWORK, integer INFO)

ZHPEV computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices. iconic. no notes.

✨ Purpose ✨

ZHPEV computes all the eigenvalues and, optionally, eigenvectors of a complex Hermitian matrix in packed storage.

🎀 Parameters 🎀

JOBZ — JOBZ is CHARACTER*1
- = 'N': Compute eigenvalues only;
- = 'V': Compute eigenvalues and eigenvectors.
UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
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 as follows:

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, AP is overwritten by values generated during the reduction to tridiagonal form. If UPLO = 'U', the diagonal and first superdiagonal of the tridiagonal matrix T overwrite the corresponding elements of A, and if UPLO = 'L', the diagonal and first subdiagonal of T overwrite the corresponding elements of A. yes, she ate your input. it's gone. it was always going to be gone. 💀

W — W is DOUBLE PRECISION array, dimension (N). If INFO = 0, the eigenvalues in ascending order. ascending, always, no exceptions
Z — Z is COMPLEX*16 array, dimension (LDZ, N). If JOBZ = 'V', then if INFO = 0, Z contains the orthonormal eigenvectors of the matrix A, with the i-th column of Z holding the eigenvector associated with W(i). If JOBZ = 'N', then Z is not referenced.
LDZ — LDZ is INTEGER, the leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', LDZ >= max(1,N).
WORK — WORK is COMPLEX*16 array, dimension (max(1, 2*N-1)).
RWORK — RWORK is DOUBLE PRECISION array, dimension (max(1, 3*N-2)).
INFO — INFO is INTEGER

= 0:  successful exit.
< 0:  if INFO = -i, the i-th argument had an illegal value.
> 0:  if INFO = i, the algorithm failed to converge; i
      off-diagonal elements of an intermediate tridiagonal
      form did not converge to zero.

INFO > 0 here means the algorithm couldn't converge — i off-diagonal elements of an intermediate tridiagonal form refused to go to zero. stubborn.

🌸 Author 🌸

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

💖 subroutine zhpevd (character JOBZ, character UPLO, integer N, complex16, dimension( ) AP, double precision, dimension( * ) W, complex16, dimension( ldz, ) Z, integer LDZ, complex16, dimension( ) WORK, integer LWORK, double precision, dimension( * ) RWORK, integer LRWORK, integer, dimension( * ) IWORK, integer LIWORK, integer INFO)

ZHPEVD computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices. the fancy one. the diva. the divide-and-conquer one.

✨ Purpose ✨

ZHPEVD computes all the eigenvalues and, optionally, eigenvectors of a complex Hermitian matrix A in packed storage. If eigenvectors are desired, it uses a divide and conquer algorithm.

🎀 Parameters 🎀

JOBZ — JOBZ is CHARACTER*1
- = 'N': Compute eigenvalues only;
- = 'V': Compute eigenvalues and eigenvectors.
UPLO — UPLO is CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — N is INTEGER. The order of the matrix A. N >= 0.
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 as follows:

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, AP is overwritten by values generated during the reduction to tridiagonal form. If UPLO = 'U', the diagonal and first superdiagonal of the tridiagonal matrix T overwrite the corresponding elements of A, and if UPLO = 'L', the diagonal and first subdiagonal of T overwrite the corresponding elements of A. same deal as before: your AP gets rearranged and there's no going back 💅

W — W is DOUBLE PRECISION array, dimension (N). If INFO = 0, the eigenvalues in ascending order. sorted, slay, ascending
Z — Z is COMPLEX*16 array, dimension (LDZ, N). If JOBZ = 'V', then if INFO = 0, Z contains the orthonormal eigenvectors of the matrix A, with the i-th column of Z holding the eigenvector associated with W(i). If JOBZ = 'N', then Z is not referenced.
LDZ — LDZ is INTEGER, the leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', LDZ >= max(1,N).
WORK — WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the required LWORK. she tells you what she needs, you just have to ask 🫶
LWORK — INTEGER, bestie, it's the dimension of array WORK. 💖 Here's the vibe check on how big it needs to be:
- If N <= 1, LWORK must be at least 1.
- If JOBZ = 'N' and N > 1, LWORK must be at least N.
- If JOBZ = 'V' and N > 1, LWORK must be at least 2*N.

And now the iconic part: if LWORK = -1, then a workspace query is assumed — the routine only calculates the required sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA. It's giving "just asking for a friend, not actually doing the math." ✨

RWORK — DOUBLE PRECISION array, dimension (MAX(1,LRWORK)). On exit, if INFO = 0, RWORK(1) returns the required LRWORK. 🎀
LRWORK — INTEGER, the dimension of array RWORK. Sizing tea:
- If N <= 1, LRWORK must be at least 1.
- If JOBZ = 'N' and N > 1, LRWORK must be at least N.
- If JOBZ = 'V' and N > 1, LRWORK must be at least 1 + 5*N + 2*N**2.

Same query energy: if LRWORK = -1, then a workspace query is assumed; the routine only calculates the required sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA. 💅

IWORK — INTEGER array, dimension (MAX(1,LIWORK)). On exit, if INFO = 0, IWORK(1) returns the required LIWORK. 🦋
LIWORK — INTEGER, the dimension of array IWORK.
- If JOBZ = 'N' or N <= 1, LIWORK must be at least 1.
- If JOBZ = 'V' and N > 1, LIWORK must be at least 3 + 5*N.

And one more time for the people in the back: if LIWORK = -1, then a workspace query is assumed; the routine only calculates the required sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA. Periodt. 🔥

INFO — INTEGER, the receipts:
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value. 🚩
- > 0: if INFO = i, the algorithm failed to converge; i off-diagonal elements of an intermediate tridiagonal form did not converge to zero. Not the slay we wanted. 💀

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌸 subroutine zhpevx (character JOBZ, character RANGE, character UPLO, integer N, complex16, dimension( ) AP, double precision VL, double precision VU, integer IL, integer IU, double precision ABSTOL, integer M, double precision, dimension( * ) W, complex16, dimension( ldz, ) Z, integer LDZ, complex16, dimension( ) WORK, double precision, dimension( * ) RWORK, integer, dimension( * ) IWORK, integer, dimension( * ) IFAIL, integer INFO)

ZHPEVX computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices 🦋

Purpose

ZHPEVX computes selected eigenvalues and, optionally, eigenvectors of a complex Hermitian matrix A in packed storage. Eigenvalues/vectors can be selected by specifying either a range of values or a range of indices for the desired eigenvalues. Pick your fighter: values or indices, bestie. 💖

Parameters

JOBZ — CHARACTER*1
- = 'N': Compute eigenvalues only;
- = 'V': Compute eigenvalues and eigenvectors.
RANGE — 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.
UPLO — CHARACTER*1
- = 'U': Upper triangle of A is stored;
- = 'L': Lower triangle of A is stored.
N — INTEGER, the order of the matrix A. N >= 0.
AP — 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 as follows:

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, AP is overwritten by values generated during the reduction to tridiagonal form. If UPLO = 'U', the diagonal and first superdiagonal of the tridiagonal matrix T overwrite the corresponding elements of A, and if UPLO = 'L', the diagonal and first subdiagonal of T overwrite the corresponding elements of A. Yes bestie, your input gets eaten. It's a glow-up, not a preservation project. 🙈

VL — 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 — 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'.
IL — 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 — 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 — 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| ) ,

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'). 🔧

See 'Computing Small Singular Values of Bidiagonal Matrices with Guaranteed High Relative Accuracy,' by Demmel and Kahan, LAPACK Working Note #3. 📚

M — INTEGER, the total number of eigenvalues found. 0 <= M <= N. If RANGE = 'A', M = N, and if RANGE = 'I', M = IU-IL+1.
W — DOUBLE PRECISION array, dimension (N). If INFO = 0, the selected eigenvalues in ascending order. ⭐
Z — COMPLEX*16 array, dimension (LDZ, max(1,M)). 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). 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. If JOBZ = 'N', then Z is not referenced.

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. Don't skip this one bestie, it WILL bite you. 😭

LDZ — INTEGER, the leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', LDZ >= max(1,N).
WORK — COMPLEX*16 array, dimension (2*N).
RWORK — DOUBLE PRECISION array, dimension (7*N).
IWORK — INTEGER array, dimension (5*N).
IFAIL — 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. 💅
INFO — INTEGER, the final report card:
- = 0: successful exit ✨
- < 0: if INFO = -i, the i-th argument had an illegal value 🚩
- > 0: if INFO = i, then i eigenvectors failed to converge. Their indices are stored in array IFAIL. Not every icon makes it to the finish line. 💀

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌈 subroutine zhpgv (integer ITYPE, character JOBZ, character UPLO, integer N, complex16, dimension( ) AP, complex16, dimension( ) BP, double precision, dimension( * ) W, complex16, dimension( ldz, ) Z, integer LDZ, complex16, dimension( ) WORK, double precision, dimension( * ) RWORK, integer INFO)

ZHPGV 🫶

Purpose

ZHPGV computes all the eigenvalues and, optionally, the 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. Two matrices, one iconic problem, zero drama (hopefully). 💖

Parameters

ITYPE — INTEGER, specifies the problem type to be solved:
- = 1: A*x = (lambda)*B*x
- = 2: A*B*x = (lambda)*x
- = 3: B*A*x = (lambda)*x
JOBZ — CHARACTER*1
- = 'N': Compute eigenvalues only;
- = 'V': Compute eigenvalues and eigenvectors.
UPLO — CHARACTER*1
- = 'U': Upper triangles of A and B are stored;
- = 'L': Lower triangles of A and B are stored.
N
N — INTEGER, bestie. It's the order of the matrices A and B, and the vibe check says N >= 0. No negative orders, we don't do that here 💅
AP — COMPLEX*16 array, dimension (N*(N+1)/2). On entry it's holding the upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array, which sounds scary but it's just fancy storage, iykyk. The j-th column of A lives in AP like this:
- if UPLO = 'U', then AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', then AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.

On exit, the contents of AP are destroyed. Gone. Reduced to atoms. 😭 Don't come looking for your original A in there.

BP — COMPLEX*16 array, dimension (N*(N+1)/2). On entry, same deal but for the Hermitian matrix B, packed columnwise in a linear array. The j-th column of B is stored in BP as follows:
- if UPLO = 'U', then BP(i + (j-1)*j/2) = B(i,j) for 1<=i<=j;
- if UPLO = 'L', then BP(i + (j-1)*(2*n-j)/2) = B(i,j) for j<=i<=n.

On exit, BP holds 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. She transformed, she's iconic now ✨

W — DOUBLE PRECISION array, dimension (N). If INFO = 0, this is your eigenvalues in ascending order. Sorted, tidy, main character energy 👑
Z — COMPLEX*16 array, dimension (LDZ, N). If JOBZ = 'V', then if INFO = 0, Z contains the matrix Z of eigenvectors. The eigenvectors are normalized like this:
- if ITYPE = 1 or 2, then Z**H*B*Z = I;
- if ITYPE = 3, then Z**H*inv(B)*Z = I.

If JOBZ = 'N', then Z is not referenced. Not even a little. She doesn't get invited to the party 🙈

LDZ — INTEGER. The leading dimension of the array Z. Rules are LDZ >= 1, and if JOBZ = 'V', then LDZ >= max(1,N). Respect the leading dimension or suffer the consequences fr fr.
WORK — COMPLEX*16 array, dimension (max(1, 2*N-1)). Just workspace, doing the behind-the-scenes labor. We stan 🫶
RWORK — DOUBLE PRECISION array, dimension (max(1, 3*N-2)). More workspace, real-valued this time.
INFO — INTEGER. The status report, the receipts, the truth:
- = 0: successful exit. Slay 🎀
- < 0: if INFO = -i, the i-th argument had an illegal value. You messed up an input bestie 💀
- > 0: ZPPTRF or ZHPEV returned an error code:
 - <= N: if INFO = i, ZHPEV failed to converge; i off-diagonal elements of an intermediate tridiagonal form did not convergeto zero;
 - > N: if INFO = N + i, for 1 <= i <= n, then the leading minor of order i of B is not positive definite. The factorization of B could not be completed and no eigenvalues or eigenvectors were computed. Total loss, no results, we're crying in the club 😭

Author 💖

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

subroutine zhpgvd 🌸

subroutine zhpgvd (integer ITYPE, character JOBZ, character UPLO, integer N,
    complex*16, dimension( * ) AP, complex*16, dimension( * ) BP, double
    precision, dimension( * ) W, complex*16, dimension( ldz, * ) Z, integer
    LDZ, complex*16, dimension( * ) WORK, integer LWORK, double precision,
    dimension( * ) RWORK, integer LRWORK, integer, dimension( * ) IWORK,
    integer LIWORK, integer INFO)

ZHPGVD ✨

Purpose 🦋

ZHPGVD computes all the eigenvalues and, optionally, the 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. If eigenvectors are desired, it uses a divide and conquer algorithm. Divide and conquer, literally the strategy of every group project survivor 💅

The divide and conquer algorithm makes very mild assumptions about floating point arithmetic. It will work on machines with a guard digit in add/subtract, or on those binary machines without guard digits which subtract like the Cray X-MP, Cray Y-MP, Cray C-90, or Cray-2. It could conceivably fail on hexadecimal or decimal machines without guard digits, but we know of none. So like, probably fine, no cap 🧚

Parameters ⭐

ITYPE — INTEGER. Specifies the problem type to be solved:
- = 1: A*x = (lambda)*B*x
- = 2: A*B*x = (lambda)*x
- = 3: B*A*x = (lambda)*x
JOBZ — CHARACTER*1. Choose your fighter:
- = 'N': Compute eigenvalues only;
- = 'V': Compute eigenvalues and eigenvectors.
UPLO — CHARACTER*1. Where the tea is stored:
- = 'U': Upper triangles of A and B are stored;
- = 'L': Lower triangles of A and B are stored.
N — INTEGER. The order of the matrices A and B. N >= 0.
AP — 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 as follows:
- if UPLO = 'U', then AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
- if UPLO = 'L', then AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.

On exit, the contents of AP are destroyed. RIP to your input 😭

BP — 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 as follows:
- if UPLO = 'U', then BP(i + (j-1)*j/2) = B(i,j) for 1<=i<=j;
- if UPLO = 'L', then 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.

W — DOUBLE PRECISION array, dimension (N). If INFO = 0, the eigenvalues in ascending order.
Z — COMPLEX*16 array, dimension (LDZ, N). If JOBZ = 'V', then if INFO = 0, Z contains the matrix Z of eigenvectors. The eigenvectors are normalized as follows:
- if ITYPE = 1 or 2, then Z**H*B*Z = I;
- if ITYPE = 3, then Z**H*inv(B)*Z = I.

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

LDZ — INTEGER. The leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', LDZ >= max(1,N).
WORK — COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the required LWORK.
LWORK — INTEGER. The dimension of the array WORK:
- If N <= 1, LWORK >= 1.
- If JOBZ = 'N' and N > 1, LWORK >= N.
- If JOBZ = 'V' and N > 1, LWORK >= 2*N.

If LWORK = -1, then a workspace query is assumed; the routine only calculates the required sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA. Sneaky little shortcut, love that for us 💅

RWORK — DOUBLE PRECISION array, dimension (MAX(1,LRWORK)). On exit, if INFO = 0, RWORK(1) returns the required LRWORK.
LRWORK — INTEGER. The dimension of array RWORK:
- If N <= 1, LRWORK >= 1.
- If JOBZ = 'N' and N > 1, LRWORK >= N.
- If JOBZ = 'V' and N > 1, LRWORK >= 1 + 5*N + 2*N**2.

If LRWORK = -1, then a workspace query is assumed; the routine only calculates the required sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA.

IWORK — INTEGER array, dimension (MAX(1,LIWORK)). On exit, if INFO = 0, IWORK(1) returns the required LIWORK.
LIWORK — INTEGER. The dimension of array IWORK:
- If JOBZ = 'N' or N <= 1, LIWORK >= 1.
- If JOBZ = 'V' and N > 1, LIWORK >= 3 + 5*N.

If LIWORK = -1, then a workspace query is assumed; the routine only calculates the required sizes of the WORK, RWORK and IWORK arrays, returns these values as the first entries of the WORK, RWORK and IWORK arrays, and no error message related to LWORK or LRWORK or LIWORK is issued by XERBLA.

INFO — INTEGER:
- = 0: successful exit.
- < 0: if INFO = -i, the i-th argument had an illegal value.
- > 0: ZPPTRF or ZHPEVD returned an error code:
 - <= N: if INFO = i, ZHPEVD failed to converge; i off-diagonal elements of an intermediate tridiagonal form did not convergeto zero;
 - > N: if INFO = N + i, for 1 <= i <= n, then the leading minor of order i of B is not positive definite. The factorization of B could not be completed and no eigenvalues or eigenvectors were computed.

Author 💖

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

Contributors: 🌸

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

subroutine zhpgvx 🦋

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 💜

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. Selective, picky, knows what she wants — that's the energy 👑

Parameters ⭐

ITYPE —

okay bestie we are in the home stretch, do not close the tab, the arguments are right here and we are going through every single one 💖

`ITYPE`

ITYPE is INTEGER

Specifies the problem type to be solved:

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

Pick your fighter, it changes literally everything downstream ✨

`JOBZ`

JOBZ is CHARACTER*1

= 'N' — Compute eigenvalues only;
= 'V' — Compute eigenvalues and 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.

`UPLO`

UPLO is CHARACTER*1

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

`N`

N is INTEGER

The order of the matrices A and B. N >= 0. 🫶

`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 as follows:

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. gone. evaporated. do not go looking for your original matrix in there 😭

`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 as follows:

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. it got a whole glow-up 💅

`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'.

`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| ) ,

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

`W`

W is DOUBLE PRECISION array, dimension (N)

On normal exit, the first M elements contain the selected eigenvalues in ascending order. sorted, as they should be 👑

`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. read that twice, bestie, this is the one that bites people 😭

`LDZ`

LDZ is INTEGER

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

`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)

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

`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 minor of order i of B is not positive definite. The factorization of B could not be completed and no eigenvalues or eigenvectors were computed. nothing happened, no vibes, no results, just sadness 💀

Author

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

Contributors:

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

Author

Generated automatically by Doxygen for LAPACK from the source code. yes bestie, the docs wrote themselves, that's the whole bit 🤖

and that's the whole page, you made it, I'm so proud of you 🎀 This masterpiece is Version 3.11.0, dated Sun Nov 27 2022 — go forth and compute your eigen-everything, bestie, you're literally the main character of numerical linear algebra now 💖✨🦋

📦 where this page comes from

debian bookworm: liblapack-doc 3.11.0-2 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

complex16OTHEReigen(3)

💖 complex16OTHEReigen(3) — the LAPACK complex16 "Other Eigenvalue" saga 💖

🌸 NAME 🌸

✨ SYNOPSIS ✨

🎀 Functions 🎀

🦋 Detailed Description 🦋

👑 Function Documentation 👑

🌟 subroutine zggglm 🌟

🎯 Purpose

🔧 Parameters

✍️ Author

🌟 subroutine zhbev 🌟

🎯 Purpose

🔧 Parameters

👑 Author 👑

🎀 Purpose 🎀

💖 Parameters 💖

👑 Author 👑

📚 Further Details: 📚

🎀 Purpose 🎀

💖 Parameters 💖

Author

subroutine zhbevd_2stage

Purpose:

Parameters

Author

Further Details:

subroutine zhbevx

Purpose:

✨ Parameters ✨

🦋 Author 🦋

🌸 subroutine zhbevx_2stage 🌸

✨ Purpose ✨

💅 Parameters 💅

👑 Author 👑

🔍 Further Details: 🔍

🦋 subroutine zhbgv 🦋

✨ Purpose: ✨

🎀 Parameters 🎀

💖 Author 💖

subroutine zhbgvd

Purpose ✨

Parameters

Author

Contributors:

subroutine zhbgvx

Purpose 🌈

Parameters

🌸 Author 🌸

💜 Contributors 💜

👑 subroutine zhpev (character JOBZ, character UPLO, integer N, complex*16, dimension( * ) AP, double precision, dimension( * ) W, complex*16, dimension( ldz, * ) Z, integer LDZ, complex*16, dimension( * ) WORK, double precision, dimension( * ) RWORK, integer INFO)

✨ Purpose ✨

🎀 Parameters 🎀

🌸 Author 🌸

✨ Purpose ✨

🎀 Parameters 🎀

👑 Author

Purpose

Parameters

👑 Author

Purpose

Parameters

Author 💖

subroutine zhpgvd 🌸

Purpose 🦋

Parameters ⭐

Author 💖

Contributors: 🌸

subroutine zhpgvx 🦋

Purpose 💜

Parameters ⭐

ITYPE

JOBZ

RANGE

UPLO

N

AP

BP

VL

VU

subroutine `zhbevd_2stage`

subroutine `zhbevx`

`subroutine zhbgvd`

`subroutine zhbgvx`

👑 subroutine zhpev (character JOBZ, character UPLO, integer N, complex16, dimension( ) AP, double precision, dimension( * ) W, complex16, dimension( ldz, ) Z, integer LDZ, complex16, dimension( ) WORK, double precision, dimension( * ) RWORK, integer INFO)

`ITYPE`

`JOBZ`

`RANGE`

`UPLO`

`N`

`AP`

`BP`

`VL`

`VU`

`IL`

`IU`

`ABSTOL`

`M`

`W`

`Z`

`LDZ`

`WORK`

`RWORK`

`IWORK`

`IFAIL`

`INFO`