/home/abui...x_2stage.f(3)

📦 version 3.12.0, in opensuse-leap 16.0

💅 /home/abui...x_2stage.f(3) — Library Functions Manual 🦋

okay bestie, so this file is called /home/abui...x_2stage.f(3) and it lives in the Library Functions Manual, and honestly? it's a whole moment. it's giving "the Fortran source walked so your eigenvalues could run" ✨

🌸 NAME 🌸

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

like, that's the whole path. yes it's long. yes it ate. no we're not shortening it, it's literal, do not touch 💅

🎀 SYNOPSIS 🎀

Functions/Subroutines

subroutine ZHEEVX_2STAGE (jobz, range, uplo, n, a, lda, vl, vu, il, iu,
    abstol, m, w, z, ldz, work, lwork, rwork, iwork, ifail, info)

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

👑 Function/Subroutine Documentation 👑

subroutine ZHEEVX_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, complex*16, dimension( *
    ) work, integer lwork, double precision, dimension( * ) rwork, integer,
    dimension( * ) iwork, integer, dimension( * ) ifail, integer info)

ZHEEVX_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for HE matrices. that's the whole vibe, bestie 🫶

✨ Purpose ✨

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

so like — you get to choose which eigenvalues you want?? iconic. main character energy fr fr 💅

🌈 Parameters 🌈

okay this is the long part, but every single one matters, no skipping, iykyk:

  • JOBZ
!> JOBZ is CHARACTER*1 !> = 'N': Compute eigenvalues only; !> = 'V': Compute eigenvalues and eigenvectors. !> Not available in this release.

so 'V' is lowkey a "we don't have that yet" situation 😭 — note that, don't come for me.

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

half-open interval (VL,VU] — yes with the round bracket on the left and the square one on the right, she's specific like that 🎀

  • UPLO
!> UPLO is CHARACTER*1 !> = 'U': Upper triangle of A is stored; !> = 'L': Lower triangle of A is stored.

pick a side bestie, we're not storing both 💀

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

⚠️ heads up: on exit part of A is destroyed — diagonal included. she does not leave things the way she found them 🙈

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

VL and VU are a matched set, VL < VU, periodt 💜

  • IL
!> IL is INTEGER !> If RANGE='I', the index of the !> smallest eigenvalue to be returned. !> 1 <= IL <= IU <= N, if N > 0; IL = 1 and IU = 0 if N = 0. !> Not referenced if RANGE = 'A' or 'V'.
  • IU
!> IU is INTEGER !> If RANGE='I', the index of the !> largest eigenvalue to be returned. !> 1 <= IL <= IU <= N, if N > 0; IL = 1 and IU = 0 if N = 0. !> Not referenced if RANGE = 'A' or 'V'.
  • ABSTOL
!> ABSTOL is DOUBLE PRECISION !> The absolute error tolerance for the eigenvalues. !> An approximate eigenvalue is accepted as converged !> when it is determined to lie in an interval [a,b] !> of width less than or equal to !> ABSTOL + EPS * max( |a|,|b| ) , !> where EPS is the machine precision. If ABSTOL is less than !> or equal to zero, then EPS*|T| will be used in its place, !> where |T| is the 1-norm of the tridiagonal matrix obtained !> by reducing A 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'). !> See by Demmel and !> Kahan, LAPACK Working Note #3.

🔥 the accuracy tea: want the most accurate eigenvalues? set ABSTOL to 2*DLAMCH('S'), not zero. and if INFO>0 (some eigenvectors didn't converge), that's your cue to switch to 2*DLAMCH('S').

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

ascending order, 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. !> 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.

⚠️ real talk: you have to make sure Z has at least max(1,M) columns. and if RANGE = 'V'? you don't even know M yet, so you gotta use an upper bound. plan ahead bestie 😭

  • 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 length of the array WORK. LWORK >= 1, when N <= 1; !> otherwise !> If JOBZ = 'N' and N > 1, LWORK must be queried. !> LWORK = MAX(1, 8*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 !> 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.

🌟 the classic move: pass LWORK = -1, ask politely, get the optimal size back in WORK(1), and XERBLA won't even yell at you about LWORK. free real estate.

also note JOBZ = 'V' with N > 1 → LWORK must be queried, and it's not yet available. yeah. that.

  • 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 💀 if an eigenvector ghosted you, its index is sitting right here.

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

a whole squad, we love a collab 🫶✨

⭐ 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

the reading list is right there, go be a scholar 🦋📚

Definition at line 303 of file zheevx_2stage.f. 🎯

Author 💖

This page was generated automatically by Doxygen for LAPACK, straight from the source code, bestie. 💅 No hand-typing drama here—Doxygen handled it, and LAPACK is the icon behind the whole thing. ✨

That's the tea! 🍓 Footer sign-off: LAPACK, Version 3.12.0, page path /home/abui...x_2stage.f(3). No date listed, just so you know 👀. Love that for us. 🫶🎀

📦 where this page comes from