heevr_2stage(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

🎀 heevr_2stage — {he,sy}evr_2stage: eig, MRRR 🎀

okay so, straight out of the Library Functions Manual — this is the LAPACK girlie who does your eigenvalues. buckle up bestie, she's long 💅

🌸 NAME 🌸

heevr_2stage — {he,sy}evr_2stage: eig, MRRR. that's it, that's the name, no cap ✨

✨ SYNOPSIS ✨

🫶 Functions

four subroutines, all iconic, all doing the eigen thing. here's the lineup 👑

  • cheevr_2stage — CHEEVR_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for HE matrices 🦋
  • dsyevr_2stage — DSYEVR_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for SY matrices 🦋
  • ssyevr_2stage — SSYEVR_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for SY matrices 🦋
  • zheevr_2stage — ZHEEVR_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for HE matrices 🦋

and their whole argument lists, verbatim, because we do not gatekeep signatures:

subroutine cheevr_2stage (jobz, range, uplo, n, a, lda, vl, vu, il, iu,
    abstol, m, w, z, ldz, isuppz, work, lwork, rwork, lrwork, iwork,
    liwork, info)
subroutine dsyevr_2stage (jobz, range, uplo, n, a, lda, vl, vu, il, iu,
    abstol, m, w, z, ldz, isuppz, work, lwork, iwork, liwork, info)
subroutine ssyevr_2stage (jobz, range, uplo, n, a, lda, vl, vu, il, iu,
    abstol, m, w, z, ldz, isuppz, work, lwork, iwork, liwork, info)
subroutine zheevr_2stage (jobz, range, uplo, n, a, lda, vl, vu, il, iu,
    abstol, m, w, z, ldz, isuppz, work, lwork, rwork, lrwork, iwork,
    liwork, info)

💫 Detailed Description 💫

so the detailed description is basically the function documentation, like it all lives down there 👇 — no separate blob of text here, that's just how this page is built. keep scrolling bestie 🫶

🦋 Function Documentation 🦋

🫶 subroutine cheevr_2stage (character jobz, character range, character uplo, integer n, complex, dimension( lda, * ) a, integer lda, real vl, real vu, integer il, integer iu, real abstol, integer m, real, dimension( * ) w, complex, dimension( ldz, * ) z, integer ldz, integer, dimension( * ) isuppz, complex, dimension( * ) work, integer lwork, real, dimension( * ) rwork, integer lrwork, integer, dimension( * ) iwork, integer liwork, integer info)

CHEEVR_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for HE matrices 💖

here's the whole thing written out properly:

subroutine cheevr_2stage (character jobz, character range, character uplo,
    integer n, complex, dimension( lda, * ) a, integer lda, real vl, real
    vu, integer il, integer iu, real abstol, integer m, real, dimension( * )
    w, complex, dimension( ldz, * ) z, integer ldz, integer, dimension( * )
    isuppz, complex, dimension( * ) work, integer lwork, real, dimension( *
    ) rwork, integer lrwork, integer, dimension( * ) iwork, integer liwork,
    integer info)

💖 Purpose

okay so the actual glow-up: CHEEVR_2STAGE computes selected eigenvalues and, optionally, eigenvectors of a complex Hermitian matrix A, and it does it using the 2stage technique for the reduction to tridiagonal. and because we're not greedy, you get to select which eigenvalues and eigenvectors you want — either by specifying a range of values or a range of indices for the desired eigenvalues ✨

here's the pipeline, bestie:

CHEEVR_2STAGE first reduces the matrix A to tridiagonal form T with a call to CHETRD. then, whenever possible, CHEEVR_2STAGE calls CSTEMR to compute the eigenspectrum using Relatively Robust Representations. CSTEMR computes eigenvalues by the dqds algorithm, while orthogonal eigenvectors are computed from various L D L^T representations (also known as Relatively Robust Representations — same thing, different outfit 💅). Gram-Schmidt orthogonalization is avoided as far as possible.

more specifically, the various steps of the algorithm are as follows — for each unreduced block (submatrix) of T:

  • (a) Compute T - sigma I = L D L^T, so that L and D define all the wanted eigenvalues to high relative accuracy. what that means: small relative changes in the entries of D and L cause only small relative changes in the eigenvalues and eigenvectors. the standard (unfactored) representation of the tridiagonal matrix T does not have this property in general. 🫠
  • (b) Compute the eigenvalues to suitable accuracy. If the eigenvectors are desired, the algorithm attains full accuracy of the computed eigenvalues only right before the corresponding vectors have to be computed — see steps c) and d).
  • (c) For each cluster of close eigenvalues, select a new shift close to the cluster, find a new factorization, and refine the shifted eigenvalues to suitable accuracy.
  • (d) For each eigenvalue with a large enough relative separation, compute the corresponding eigenvector by forming a rank revealing twisted factorization. then go back to (c) for any clusters that remain. 🔁

the desired accuracy of the output can be specified by the input parameter ABSTOL — she's the main character of accuracy here, periodt.

for more details, see CSTEMR's documentation and:

  • Inderjit S. Dhillon and Beresford N. Parlett: Linear Algebra and its Applications, 387(1), pp. 1-28, August 2004.
  • Inderjit Dhillon and Beresford Parlett: SIAM Journal on Matrix Analysis and Applications, Vol. 25, 2004. Also LAPACK Working Note 154.
  • Inderjit Dhillon: , Computer Science Division Technical Report No. UCB/CSD-97-971, UC Berkeley, May 1997.
Note 1 🧚: CHEEVR_2STAGE calls CSTEMR when the full spectrum is requested on machines which conform to the ieee-754 floating point standard. CHEEVR_2STAGE calls SSTEBZ and CSTEIN on non-ieee machines and when partial spectrum requests are made.
⚠️ real talk, this one matters: normal execution of CSTEMR may create NaNs and infinities, and hence may abort due to a floating point exception in environments which do not handle NaNs and infinities in the ieee standard default manner. not a vibe, but it's the truth 💀

🍓 Parameters

JOBZ — she's CHARACTER*1, and she decides your whole destiny:

  • = 'N': Compute eigenvalues only
  • = 'V': Compute eigenvalues and eigenvectors. Not available in this release 🥲

RANGE — also CHARACTER*1, tells us which eigenvalues we're hunting:

  • = '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.

For RANGE = 'V' or 'I' and IU - IL < N - 1, SSTEBZ and CSTEIN are called.

UPLO — CHARACTER*1, pick a triangle, any triangle:

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

N — INTEGER. the order of the matrix A. N >= 0.

A — COMPLEX array, dimension (LDA, N).

On entry, the Hermitian matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of A contains the upper triangular part of the matrix A. If UPLO = 'L', the leading N-by-N lower triangular part of A contains the lower triangular part of the matrix A.

On exit, the lower triangle (if UPLO='L') or the upper triangle (if UPLO='U') of A, including the diagonal, is destroyed 💀 (she did her job and she's not coming back).

LDA — INTEGER. the leading dimension of the array A. LDA >= max(1,N).

VL — REAL. If RANGE='V', the lower bound of the interval to be searched for eigenvalues. VL < VU. Not referenced if RANGE = 'A' or 'I'.

VU — REAL. 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 — REAL. 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 A to tridiagonal form.

See by Demmel and Kahan, LAPACK Working Note #3.

If high relative accuracy is important, set ABSTOL to SLAMCH( 'Safe minimum' ). Doing so will guarantee that eigenvalues are computed to high relative accuracy when possible in future releases. The current code does not make any guarantees about high relative accuracy, but future releases will. See J. Barlow and J. Demmel, , LAPACK Working Note #7, for a discussion of which matrices define their eigenvalues to high relative accuracy 🎀

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 — REAL array, dimension (N). the first M elements contain the selected eigenvalues in ascending order ⬆️✨

Z — COMPLEX 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 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 accordingly bestie 🙈

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

ISUPPZ — okay so this one's whole description is dropping in the next part, and it's gonna be good 💖 (part 1 says bye for now, no sign-off, just vibes ✨)

  • ISUPPZ — okay so this is an INTEGER array, dimension ( 2*max(1,M) ). It’s the support of the eigenvectors in Z, aka the indices that show which elements in Z are nonzero. The i-th eigenvector is nonzero only in elements ISUPPZ( 2*i-1 ) through ISUPPZ( 2*i ). This is an output of CSTEMR (tridiagonal matrix). The support of the eigenvectors of A is typically 1:N because of the unitary transformations applied by CUNMTR. Implemented only for RANGE = 'A' or 'I' and IU - IL = N - 1. 💅
  • WORK — WORK is COMPLEX 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 queried:

LWORK = MAX(1, 26*N, dimension) where
        dimension = max(stage1,stage2) + (KD+1)*N + N
                  = N*KD + N*max(KD+1,FACTOPTNB)
                    + max(2*KD*KD, KD*NTHREADS)
                    + (KD+1)*N + N

where KD is the blocking size of the reduction, FACTOPTNB is the blocking used by the QR or LQ algorithm — usually FACTOPTNB=128 is a good choice — and 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. 🫶

  • RWORK — RWORK is REAL array, dimension (MAX(1,LRWORK)). On exit, if INFO = 0, RWORK(1) returns the optimal (and minimal) LRWORK. 🎀
  • LRWORK — LRWORK is INTEGER, the length of the array RWORK. If N <= 1, LRWORK >= 1, else LRWORK >= 24*N.

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 (and minimal) LIWORK. 🌸
  • LIWORK — LIWORK is INTEGER, the dimension of the array IWORK. If N <= 1, LIWORK >= 1, else LIWORK >= 10*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: Internal error 💀

👑 Author 👑

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🫶 Contributors 🫶

  • Inderjit Dhillon, IBM Almaden, USA
  • Osni Marques, LBNL/NERSC, USA
  • Ken Stanley, Computer Science Division, University of California at Berkeley, USA
  • Jason Riedy, Computer Science Division, University of California at Berkeley, USA

🔥 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

Definition at line 405 of file cheevr_2stage.f.

🌈 subroutine dsyevr_2stage 🌈

subroutine dsyevr_2stage (character jobz, character range, character uplo,
    integer n, double precision, dimension( lda, * ) a, integer lda, double
    precision vl, double precision vu, integer il, integer iu, double
    precision abstol, integer m, double precision, dimension( * ) w, double
    precision, dimension( ldz, * ) z, integer ldz, integer, dimension( * )
    isuppz, double precision, dimension( * ) work, integer lwork, integer,
    dimension( * ) iwork, integer liwork, integer info)

DSYEVR_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for SY matrices. 👑

✨ Purpose ✨

Okay bestie, here’s the vibe: DSYEVR_2STAGE computes selected eigenvalues and, optionally, eigenvectors of a real symmetric 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. 🌟

DSYEVR_2STAGE first reduces the matrix A to tridiagonal form T with a call to DSYTRD. Then, whenever possible, DSYEVR_2STAGE calls DSTEMR to compute the eigenspectrum using Relatively Robust Representations. DSTEMR computes eigenvalues by the dqds algorithm, while orthogonal eigenvectors are computed from various L D L^T representations (also known as Relatively Robust Representations). Gram-Schmidt orthogonalization is avoided as far as possible. More specifically, the various steps of the algorithm are as follows. 🧚

For each unreduced block (submatrix) of T:

  1. (a) Compute T - sigma I = L D L^T, so that L and D define all the wanted eigenvalues to high relative accuracy. This means that small relative changes in the entries of D and L cause only small relative changes in the eigenvalues and eigenvectors. The standard (unfactored) representation of the tridiagonal matrix T does not have this property in general. 💜
  2. (b) Compute the eigenvalues to suitable accuracy. If the eigenvectors are desired, the algorithm attains full accuracy of the computed eigenvalues only right before the corresponding vectors have to be computed, see steps c) and d). 🔥
  3. (c) For each cluster of close eigenvalues, select a new shift close to the cluster, find a new factorization, and refine the shifted eigenvalues to suitable accuracy. 🌸
  4. (d) For each eigenvalue with a large enough relative separation compute the corresponding eigenvector by forming a rank revealing twisted factorization. Go back to (c) for any clusters that remain. 🦋

The desired accuracy of the output can be specified by the input parameter ABSTOL. ✨

For more details, see DSTEMR's documentation and:

  • Inderjit S. Dhillon and Beresford N. Parlett: Linear Algebra and its Applications, 387(1), pp. 1-28, August 2004.
  • Inderjit Dhillon and Beresford Parlett: SIAM Journal on Matrix Analysis and Applications, Vol. 25, 2004. Also LAPACK Working Note 154.
  • Inderjit Dhillon: , Computer Science Division Technical Report No. UCB/CSD-97-971, UC Berkeley, May 1997.
Note 1 : DSYEVR_2STAGE calls DSTEMR when the full spectrum is requested on machines which conform to the ieee-754 floating point standard. DSYEVR_2STAGE calls DSTEBZ and SSTEIN on non-ieee machines and when partial spectrum requests are made.
Normal execution of DSTEMR may create NaNs and infinities and hence may abort due to a floating point exception in environments which do not handle NaNs and infinities in the ieee standard default manner. 😭

🎀 Parameters 🎀

  • JOBZ — JOBZ is CHARACTER*1.
    • = 'N': Compute eigenvalues only;
    • = 'V': Compute eigenvalues and eigenvectors. Not available in this release.
  • 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. For RANGE = 'V' or 'I' and IU - IL < N - 1, DSTEBZ and DSTEIN are called. 💅
  • 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. 🌟
  • A —
  • A — DOUBLE PRECISION array, dimension (LDA, N). On entry, this is the symmetric matrix A, bestie. If UPLO = 'U', the leading N-by-N upper triangular part of A holds the upper triangular part of the matrix A. If UPLO = 'L', the leading N-by-N lower triangular part of A holds the lower triangular part of the matrix A. On exit? The lower triangle (if UPLO='L') or the upper triangle (if UPLO='U') of A, including the diagonal, is straight-up destroyed 💀. Like, gone. So don't come looking for it later.
  • LDA — INTEGER. The leading dimension of the array A. Constraint: LDA >= max(1,N). Non-negotiable 🫶.
  • VL — DOUBLE PRECISION. If RANGE='V', this is the lower bound of the interval to be searched for eigenvalues, and VL < VU. Not referenced at all if RANGE = 'A' or 'I' — it just sits there, unbothered 💅.
  • VU — DOUBLE PRECISION. If RANGE='V', this is the upper bound of the interval to be searched for eigenvalues, and again VL < VU. Not referenced if RANGE = 'A' or 'I'.
  • IL — INTEGER. If RANGE='I', this is the index of the smallest eigenvalue to be returned. Constraint: 1 <= IL <= IU <= N, if N > 0; and IL = 1 and IU = 0 if N = 0. Not referenced if RANGE = 'A' or 'V'.
  • IU — INTEGER. If RANGE='I', this is the index of the largest eigenvalue to be returned. Constraint: 1 <= IL <= IU <= N, if N > 0; and 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 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| is used in its place, where |T| is the 1-norm of the tridiagonal matrix you get by reducing A to tridiagonal form.

See the work by Demmel and Kahan, LAPACK Working Note #3.

If high relative accuracy is important to you, set ABSTOL to DLAMCH( 'Safe minimum' ). Doing that will guarantee eigenvalues are computed to high relative accuracy when possible in future releases. Ngl, the current code makes no guarantees about high relative accuracy — but future releases will. See J. Barlow and J. Demmel, LAPACK Working Note #7, for a whole discussion of which matrices define their eigenvalues to high relative accuracy 👑

  • M — INTEGER. The total number of eigenvalues found, with 0 <= M <= N. If RANGE = 'A', then M = N, and if RANGE = 'I', then M = IU-IL+1.
  • W — DOUBLE PRECISION array, dimension (N). The first M elements contain the selected eigenvalues in ascending order. Iconic, sorted, organized 🎀.
  • Z — DOUBLE PRECISION 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 JOBZ = 'N', then Z is not referenced at all. 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 and you have to use an upper bound. Supplying N columns is always safe 🫶.
  • LDZ — INTEGER. The leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', then LDZ >= max(1,N).
  • ISUPPZ — INTEGER array, dimension ( 2*max(1,M) ). The support of the eigenvectors in Z, i.e. the indices indicating the nonzero elements in Z. The i-th eigenvector is nonzero only in elements ISUPPZ( 2*i-1 ) through ISUPPZ( 2*i ). This is an output of DSTEMR (tridiagonal matrix). The support of the eigenvectors of A is typically 1:N because of the orthogonal transformations applied by DORMTR. Implemented only for RANGE = 'A' or 'I' and IU - IL = N - 1 — so don't come for it outside those conditions 🙈.
  • WORK — DOUBLE PRECISION array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, then WORK(1) returns the optimal LWORK 💖.
  • LWORK — INTEGER. The dimension of the array WORK. If N <= 1, then LWORK must be at least 1. If JOBZ = 'N' and N > 1, LWORK must be queried.
LWORK = MAX(1, 26*N, dimension) where
        dimension = max(stage1,stage2) + (KD+1)*N + 5*N
                  = N*KD + N*max(KD+1,FACTOPTNB)
                    + max(2*KD*KD, KD*NTHREADS)
                    + (KD+1)*N + 5*N

where KD is the blocking size of the reduction, FACTOPTNB is the blocking used by the QR or LQ algorithm (usually FACTOPTNB=128 is a good choice), and NTHREADS is the number of threads used when openMP compilation is enabled, otherwise =1.

If JOBZ = 'V' and N > 1, LWORK must be queried too — not yet available 😭.

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.

  • IWORK — INTEGER array, dimension (MAX(1,LIWORK)). On exit, if INFO = 0, IWORK(1) returns the optimal LIWORK ✨.
  • LIWORK — INTEGER. The dimension of the array IWORK. If N <= 1, then LIWORK >= 1, else LIWORK >= 10*N.

If LIWORK = -1, then a workspace query is assumed: the routine only calculates the optimal size of the IWORK array, returns this value as the first entry of the IWORK array, and no error message related to LIWORK is issued by XERBLA.

  • INFO — INTEGER. The vibe check at the end 👑:
    • = 0: successful exit, slay 🎉
    • < 0: if INFO = -i, the i-th argument had an illegal value
    • > 0: Internal error 💀

💜 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🌸 Contributors:

Inderjit Dhillon, IBM Almaden, USA

Osni Marques, LBNL/NERSC, USA

Ken Stanley, Computer Science Division, University of California at Berkeley, USA

Jason Riedy, Computer Science Division, University of California at Berkeley, USA

⭐ Further Details:

All the details about the 2stage techniques are available in — and bestie, this is the reading list, no cap 📚:

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

Definition at line 380 of file dsyevr_2stage.f.

subroutine ssyevr_2stage (character jobz, character range, character uplo,
    integer n, real, dimension( lda, * ) a, integer lda, real vl, real vu,
    integer il, integer iu, real abstol, integer m, real, dimension( * ) w,
    real, dimension( ldz, * ) z, integer ldz, integer, dimension( * )
    isuppz, real, dimension( * ) work, integer lwork, integer, dimension( *
    ) iwork, integer liwork, integer info)

SSYEVR_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for SY matrices 🦋

✨ Purpose:

okay so this is the part where it actually explains itself 💅 —

okay so real quick, before we get into the parameter tea 🍵 — what is this subroutine actually doing? SSYEVR_2STAGE computes selected eigenvalues and, if you want them, eigenvectors too, of a real symmetric matrix A, and it does it with the 2stage technique for the reduction to tridiagonal. You get to pick which eigenvalues you want by giving either a range of values or a range of indices. choose your fighter 💅

Here's the pipeline: SSYEVR_2STAGE first reduces the matrix A to tridiagonal form T by calling SSYTRD. Then, whenever it possibly can, SSYEVR_2STAGE calls SSTEMR to compute the eigenspectrum using Relatively Robust Representations. SSTEMR computes eigenvalues via the dqds algorithm, and the orthogonal eigenvectors come out of various L D L^T representations (those are the Relatively Robust Representations, iykyk). Gram-Schmidt orthogonalization? avoided as far as possible, we simply do not have the time 🫶

More specifically, the steps of the algorithm are literally:

  1. For each unreduced block (submatrix) of T:
    • (a) Compute T - sigma I = L D L^T, so that L and D define all the wanted eigenvalues to high relative accuracy. That means small relative changes in the entries of D and L cause only small relative changes in the eigenvalues and eigenvectors. The standard (unfactored) representation of the tridiagonal matrix T does not have this property in general. bestie it's giving fragile 🌸
    • (b) Compute the eigenvalues to suitable accuracy. If the eigenvectors are desired, the algorithm attains full accuracy of the computed eigenvalues only right before the corresponding vectors have to be computed — see steps c) and d).
    • (c) For each cluster of close eigenvalues, pick a new shift close to the cluster, find a new factorization, and refine the shifted eigenvalues to suitable accuracy.
    • (d) For each eigenvalue with a large enough relative separation, compute the corresponding eigenvector by forming a rank revealing twisted factorization. Then go back to (c) for any clusters that remain.

The desired accuracy of the output is yours to specify via the input parameter ABSTOL. iconique ✨

For more details, see SSTEMR's documentation and:

  • Inderjit S. Dhillon and Beresford N. Parlett: Linear Algebra and its Applications, 387(1), pp. 1-28, August 2004.
  • Inderjit Dhillon and Beresford Parlett: SIAM Journal on Matrix Analysis and Applications, Vol. 25, 2004. Also LAPACK Working Note 154.
  • Inderjit Dhillon: , Computer Science Division Technical Report No. UCB/CSD-97-971, UC Berkeley, May 1997.

(yes the title on that third one is genuinely blank in the source, not me being lazy 🙈)

Note 1 🎀: SSYEVR_2STAGE calls SSTEMR when the full spectrum is requested on machines which conform to the ieee-754 floating point standard. SSYEVR_2STAGE calls SSTEBZ and SSTEIN on non-ieee machines and when partial spectrum requests are made.

⚠️ heads up, this is the important one: normal execution of SSTEMR may create NaNs and infinities, and hence may abort due to a floating point exception in environments which do not handle NaNs and infinities in the ieee standard default manner. not a drill 💀

💖 Parameters 💖

Time to meet the cast. every single one, no skips 💅

JOBZ

JOBZ is CHARACTER*1

  • 'N': compute eigenvalues only
  • 'V': compute eigenvalues and eigenvectors. Not available in this release.

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.

For RANGE = 'V' or 'I' and IU - IL < N - 1, SSTEBZ and SSTEIN are called. (tl;dr the vibes switch up 😌)

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.

A

A is REAL array, dimension (LDA, N)

On entry, the symmetric matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of A contains the upper triangular part of the matrix A. If UPLO = 'L', the leading N-by-N lower triangular part of A contains the lower triangular part of the matrix A.

🫶 on exit, the lower triangle (if UPLO='L') or the upper triangle (if UPLO='U') of A, including the diagonal, is destroyed. she ate and left no crumbs, unfortunately your matrix is the crumbs 😭

LDA

LDA is INTEGER

The leading dimension of the array A. LDA >= max(1,N).

VL

VL is REAL

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 REAL

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 REAL

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 A to tridiagonal form. 🦋

See by Demmel and Kahan, LAPACK Working Note #3. (again — blank title in the source, not me, don't come for me 🙈)

If high relative accuracy is important, set ABSTOL to SLAMCH( 'Safe minimum' ). Doing so will guarantee that eigenvalues are computed to high relative accuracy when possible in future releases. The current code does not make any guarantees about high relative accuracy, but future releases will. 👑 See J. Barlow and J. Demmel, , LAPACK Working Note #7, for a discussion of which matrices define their eigenvalues to high relative accuracy.

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 REAL array, dimension (N)

The first M elements contain the selected eigenvalues in ascending order. sorted, as she should be ✨

Z

Z is REAL 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 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. Supplying N columns is always safe. when in doubt, just give it N, bestie, it's free real estate 💜

LDZ

LDZ is INTEGER

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

ISUPPZ

ISUPPZ is INTEGER array, dimension ( 2*max(1,M) )

The support of the eigenvectors in Z, i.e., the indices indicating the nonzero elements in Z. The i-th eigenvector is nonzero only in elements ISUPPZ( 2*i-1 ) through ISUPPZ( 2*i ). This is an output of SSTEMR (tridiagonal matrix). The support of the eigenvectors of A is typically 1:N because of the orthogonal transformations applied by SORMTR. Implemented only for RANGE = 'A' or 'I' and IU - IL = N - 1. ngl that last line is doing a little gatekeeping 🌈

WORK

WORK is REAL array, dimension (MAX(1,LWORK))

On exit, if INFO = 0, WORK(1) returns the optimal LWORK.

LWORK — okay this one's deets are literally the next part, hold that thought 💅

  • LWORK — this one's an INTEGER, the dimension of the array WORK. And bestie, the sizing rules here are a whole saga so eyes up:
    • If N <= 1, LWORK must be at least 1. That's it, that's the whole vibe for tiny problems.
    • If JOBZ = 'N' and N > 1, LWORK must be queried — no guessing, no yolo-ing a number. The formula is:
LWORK = MAX(1, 26*N, dimension) where
        dimension = max(stage1,stage2) + (KD+1)*N + 5*N
                  = N*KD + N*max(KD+1,FACTOPTNB)
                    + max(2*KD*KD, KD*NTHREADS)
                    + (KD+1)*N + 5*N

and like, what are those things? Ok so:

  • KD is the blocking size of the reduction 🌸
  • FACTOPTNB is the blocking used by the QR or LQ algorithm — usually FACTOPTNB=128 is a good choice, noted 💅
  • NTHREADS is the number of threads used when openMP compilation is enabled, otherwise =1.
  • If JOBZ = 'V' and N > 1, LWORK must also be queried. Not yet available though 🙈 — like, the door's not open yet, so don't come knocking.

And the iconic workspace-query clause: 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. It's like asking "how much room do I need" and getting the number back instead of a whole computation. 🎀

  • IWORK — an INTEGER array, dimension (MAX(1,LIWORK)). On exit, if INFO = 0, IWORK(1) returns the optimal LIWORK. So it tells you the optimal size on the way out, cute right? ✨
  • LIWORK — INTEGER, the dimension of the array IWORK. Rules: if N <= 1, LIWORK >= 1, else LIWORK >= 10*N.

Same query energy: if LIWORK = -1, then a workspace query is assumed. The routine only calculates the optimal size of the IWORK array, returns this value as the first entry of the IWORK array, and no error message related to LIWORK is issued by XERBLA. 💫

  • INFO — INTEGER, the receipts:
    • = 0: successful exit 🎉 slay
    • < 0: if INFO = -i, the i-th argument had an illegal value — so go count your arguments, bestie
    • > 0: Internal error 💀

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Contributors:

Inderjit Dhillon, IBM Almaden, USA

Osni Marques, LBNL/NERSC, USA

Ken Stanley, Computer Science Division, University of California at Berkeley, USA

Jason Riedy, Computer Science Division, University of California at Berkeley, USA

Further Details:

Ok so if you really wanna go deep — and honestly, respect — all details about the 2stage techniques are available in these papers 👑:

  • 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

Definition at line 380 of file ssyevr_2stage.f.

🦋 subroutine zheevr_2stage 🦋

Here's the signature, character for character, because bestie we do not paraphrase types:

subroutine zheevr_2stage (character jobz, character range, character uplo,
    integer n, complex*16, dimension( lda, * ) a, integer lda, 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, integer, dimension( * )
    isuppz, complex*16, dimension( * ) work, integer lwork, double
    precision, dimension( * ) rwork, integer lrwork, integer, dimension( * )
    iwork, integer liwork, integer info)

ZHEEVR_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for HE matrices. 💜

✨ Purpose ✨

ZHEEVR_2STAGE computes selected eigenvalues and, optionally, eigenvectors of a complex Hermitian 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. Very choose-your-own-adventure of it. 🌈

So here's the pipeline: ZHEEVR_2STAGE first reduces the matrix A to tridiagonal form T with a call to ZHETRD. Then, whenever possible, ZHEEVR_2STAGE calls ZSTEMR to compute the eigenspectrum using Relatively Robust Representations. ZSTEMR computes eigenvalues by the dqds algorithm, while orthogonal eigenvectors are computed from various L D L^T representations (also known as Relatively Robust Representations). Gram-Schmidt orthogonalization is avoided as far as possible. Iconic behaviour honestly. More specifically, the various steps of the algorithm are as follows:

For each unreduced block (submatrix) of T,

  1. (a) Compute T - sigma I = L D L^T, so that L and D define all the wanted eigenvalues to high relative accuracy. This means that small relative changes in the entries of D and L cause only small relative changes in the eigenvalues and eigenvectors. The standard (unfactored) representation of the tridiagonal matrix T does not have this property in general. 😤 rude of it.
  2. (b) Compute the eigenvalues to suitable accuracy. If the eigenvectors are desired, the algorithm attains full accuracy of the computed eigenvalues only right before the corresponding vectors have to be computed — see steps c) and d). Last-minute era. ⏰
  3. (c) For each cluster of close eigenvalues, select a new shift close to the cluster, find a new factorization, and refine the shifted eigenvalues to suitable accuracy.
  4. (d) For each eigenvalue with a large enough relative separation compute the corresponding eigenvector by forming a rank revealing twisted factorization. Go back to (c) for any clusters that remain. 🔁

The desired accuracy of the output can be specified by the input parameter ABSTOL. You're in control, bestie. 🫶

For more details, see ZSTEMR's documentation and:

  • Inderjit S. Dhillon and Beresford N. Parlett: Linear Algebra and its Applications, 387(1), pp. 1-28, August 2004.
  • Inderjit Dhillon and Beresford Parlett: SIAM Journal on Matrix Analysis and Applications, Vol. 25, 2004. Also LAPACK Working Note 154.
  • Inderjit Dhillon: , Computer Science Division Technical Report No. UCB/CSD-97-971, UC Berkeley, May 1997.
Note 1 : ZHEEVR_2STAGE calls ZSTEMR when the full spectrum is requested on machines which conform to the ieee-754 floating point standard. ZHEEVR_2STAGE calls DSTEBZ and ZSTEIN on non-ieee machines and when partial spectrum requests are made.
Big warning, no cap 🔥: Normal execution of ZSTEMR may create NaNs and infinities and hence may abort due to a floating point exception in environments which do not handle NaNs and infinities in the ieee standard default manner. So like, if your environment is weird about NaN, this could just ✨perish✨. You've been warned 💀.

Parameters

  • JOBZ — JOBZ is CHARACTER*1.
    • = 'N': Compute eigenvalues only;
    • = 'V': Compute eigenvalues and eigenvectors. Not available in this release. 🙈 (yes, again)
  • 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.

For RANGE = 'V' or 'I' and IU - IL < N - 1, DSTEBZ and ZSTEIN are called. iykyk 💅

  • 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. 🌸
  • A — A is COMPLEX*16 array, dimension (LDA, N).

On entry, the Hermitian matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of A contains the upper triangular part of the matrix A. If UPLO = 'L', the leading N-by-N lower triangular part of A contains the lower triangular part of the matrix A.

On exit, the lower triangle (if UPLO='L') or the upper triangle (if UPLO='U') of A, including the diagonal, is destroyed. 😭 gone. reduced to atoms. that's just how it is.

  • LDA — LDA is INTEGER, the leading dimension of the array A. LDA >= max(1,N). 🎀
  • 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' — so don't stress about it then. ✨
  • 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'. Same deal, upper version. 🦋
  • 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'. Note the little edge case for N = 0 there, it's giving attention to detail 👑
  • IU
  • IU — INTEGER. Bestie, this one only matters if RANGE='I': it's the index of the largest eigenvalue you want back. Rules: 1 <= IL <= IU <= N when N > 0; and when N = 0 you get IL = 1 and IU = 0. Totally 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'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| will be used in its place, where |T| is the 1-norm of the tridiagonal matrix obtained by reducing A to tridiagonal form. 🧮

See the work by Demmel and Kahan, LAPACK Working Note #3.

If high relative accuracy is important, set ABSTOL to DLAMCH( 'Safe minimum' ). Doing so will guarantee that eigenvalues are computed to high relative accuracy when possible in future releases — the current code does not make any guarantees about high relative accuracy, but future releases will (fr fr, pinky promise 🌸). See J. Barlow and J. Demmel, LAPACK Working Note #7, for a discussion of which matrices define their eigenvalues to high relative accuracy.

  • M — 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 is mathing ✨
  • W — DOUBLE PRECISION array, dimension (N). The first M elements contain the selected eigenvalues in ascending order. Sorted, iconic, no notes. 👑
  • 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 JOBZ = 'N', then Z is not referenced at all, she's off duty 💅
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. Heads up bestie, you gotta over-provision 🙈
  • LDZ — INTEGER. The leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', LDZ >= max(1,N). Respect the leading dimension, she's the main character 💖
  • ISUPPZ — INTEGER array, dimension ( 2*max(1,M) ). The support of the eigenvectors in Z, i.e. the indices indicating the nonzero elements in Z. The i-th eigenvector is nonzero only in elements ISUPPZ( 2*i-1 ) through ISUPPZ( 2*i ). This is an output of ZSTEMR (tridiagonal matrix). The support of the eigenvectors of A is typically 1:N because of the unitary transformations applied by ZUNMTR. Implemented only for RANGE = 'A' or 'I' and IU - IL = N - 1. 🦋
  • WORK — COMPLEX*16 array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. She's telling you what she needs, listen to her 🫶
  • LWORK — 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 queried:

LWORK = MAX(1, 26*N, dimension) where
        dimension = max(stage1,stage2) + (KD+1)*N + N
                  = N*KD + N*max(KD+1,FACTOPTNB)
                    + max(2*KD*KD, KD*NTHREADS)
                    + (KD+1)*N + N
        where KD is the blocking size of the reduction,
        FACTOPTNB is the blocking used by the QR or LQ
        algorithm, usually FACTOPTNB=128 is a good choice
        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 😭 (yes, we're all waiting).

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. Sneaky lil peek mode, she ate 🔥

  • RWORK — DOUBLE PRECISION array, dimension (MAX(1,LRWORK)). On exit, if INFO = 0, RWORK(1) returns the optimal (and minimal) LRWORK. 💜
  • LRWORK — INTEGER. The length of the array RWORK. If N <= 1, LRWORK >= 1, else LRWORK >= 24*N.

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 — INTEGER array, dimension (MAX(1,LIWORK)). On exit, if INFO = 0, IWORK(1) returns the optimal (and minimal) LIWORK. ⭐
  • LIWORK — INTEGER. The dimension of the array IWORK. If N <= 1, LIWORK >= 1, else LIWORK >= 10*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 — INTEGER, the vibe report:
= 0:  successful exit
< 0:  if INFO = -i, the i-th argument had an illegal value
> 0:  Internal error

So 0 is slay, negative means you passed something cursed (INFO = -i → the i-th argument had an illegal value 😬), and positive means something broke internally, not your fault king 💀

👑 Author

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

🫶 Contributors

  • Inderjit Dhillon, IBM Almaden, USA
  • Osni Marques, LBNL/NERSC, USA
  • Ken Stanley, Computer Science Division, University of California at Berkeley, USA
  • Jason Riedy, Computer Science Division, University of California at Berkeley, USA

🔬 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

Definition at line 405 of file zheevr_2stage.f.

🌸 Author

Generated automatically by Doxygen for LAPACK from the source code.

That's the whole page bestie, we made it to the end 🎀 ngl this was a marathon and you ate. This lil beauty is LAPACK Version 3.12.0, page heevr_2stage(3) — go forth and diagonalize responsibly 💅✨

📦 where this page comes from