SRC/cheevd_2stage.f(3)

📦
version 3.12.1 · 4 versions
, in arch rolling

💅 SRC/cheevd_2stage.f(3) — LAPACK Library Functions Manual

okay bestie, welcome to the group chat 💖 this is the SRC/cheevd_2stage.f page, straight out of the LAPACK manual. Buckle up, we're doing eigenvalues.

✨ NAME ✨

SRC/cheevd_2stage.f — that's the file, that's the name, no notes.

🦋 SYNOPSIS 🦋

Functions/Subroutines

subroutine cheevd_2stage (jobz, uplo, n, a, lda, w, work, lwork, rwork,
    lrwork, iwork, liwork, info)

and what does it do? it CHEEVD_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for HE matrices. iconic behaviour honestly 👑

🌸 Function/Subroutine Documentation 🌸

subroutine cheevd_2stage

subroutine cheevd_2stage (character jobz, character uplo, integer n,
    complex, dimension( lda, * ) a, integer lda, real, dimension( * ) w,
    complex, dimension( * ) work, integer lwork, real, dimension( * ) rwork,
    integer lrwork, integer, dimension( * ) iwork, integer liwork, integer
    info)

CHEEVD_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for HE matrices — she said it twice because she means it, periodt.

Purpose 🎀

!>
!> CHEEVD_2STAGE computes all eigenvalues and, optionally, eigenvectors of a
!> complex Hermitian matrix A using the 2stage technique for
!> the reduction to tridiagonal.  If eigenvectors are desired, it uses a
!> divide and conquer algorithm.
!>
!>

so: all the eigenvalues, and if you want them, the eigenvectors too, of a complex Hermitian matrix A. the reduction to tridiagonal? done with the 2stage technique, that's the whole vibe. and if you do want eigenvectors, it hits them with a divide and conquer algorithm. ate 💅

Parameters 🫶

literally every single one, in order, no skipping:

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

so 'N' = eigenvalues only. 'V' = eigenvalues and eigenvectors… except 'V' is not available in this release, okay bestie don't come for me, that's just what it says 😭

  • UPLO — also CHARACTER*1, pick your triangle:
!>          UPLO is CHARACTER*1
!>          = 'U':  Upper triangle of A is stored;
!>          = 'L':  Lower triangle of A is stored.
!>
  • N — INTEGER, the order of the matrix A. and N >= 0. that's it, that's the rule.
  • A — COMPLEX array, dimension (LDA, N). on entry, it's the Hermitian matrix A:
!>          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, if JOBZ = 'V', then if INFO = 0, A contains the
!>          orthonormal eigenvectors of the matrix A.
!>          If JOBZ = 'N', then on exit the lower triangle (if UPLO='L')
!>          or the upper triangle (if UPLO='U') of A, including the
!>          diagonal, is destroyed.
!>
⚠️ bestie hear me — with JOBZ = 'N', your triangle of A including the diagonal gets destroyed on exit. gone. evaporated. back up your data first fr fr 💀
  • LDA — INTEGER, the leading dimension of the array A. must be LDA >= max(1,N).
  • W — REAL array, dimension (N). if INFO = 0, this is where the eigenvalues live, in ascending order 🌈
  • WORK — COMPLEX array, dimension (MAX(1,LWORK)). on exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  • LWORK — INTEGER, the dimension of the array WORK. and here's the whole deal:
!>          If N <= 1,               LWORK must be at least 1.
!>          If JOBZ = 'N' and N > 1, LWORK must be queried.
!>                                   LWORK = MAX(1, dimension) where
!>                                   dimension = max(stage1,stage2) + (KD+1)*N + N+1
!>                                             = N*KD + N*max(KD+1,FACTOPTNB)
!>                                               + max(2*KD*KD, KD*NTHREADS)
!>                                               + (KD+1)*N + N+1
!>                                   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 at least 2*N + 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.
!>

the way this formula goes on forever 😭 but it's all there — KD is the blocking size of the reduction, FACTOPTNB is the blocking used by the QR or LQ algorithm (and usually FACTOPTNB=128 is a good choice, noted ✨), and NTHREADS is the number of threads when openMP compilation is enabled, otherwise it's =1.

and LWORK = -1? that's a workspace query — it only calculates the optimal sizes of WORK, RWORK and IWORK, hands them back as the first entries of those arrays, and XERBLA stays quiet about LWORK/LRWORK/LIWORK. no drama 🎀

  • RWORK — REAL array, dimension (LRWORK). on exit, if INFO = 0, RWORK(1) returns the optimal LRWORK.
  • LRWORK — INTEGER, the dimension of 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 — INTEGER array, dimension (MAX(1,LIWORK)). on exit, if INFO = 0, IWORK(1) returns the optimal LIWORK.
  • LIWORK — INTEGER, the dimension of IWORK:
!>          If N <= 1,                LIWORK must be at least 1.
!>          If JOBZ  = 'N' and 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 — INTEGER, the vibe check at the end:
!>          = 0:  successful exit
!>          < 0:  if INFO = -i, the i-th argument had an illegal value
!>          > 0:  if INFO = i and JOBZ = 'N', then the algorithm failed
!>                to converge; i off-diagonal elements of an intermediate
!>                tridiagonal form did not converge to zero;
!>                if INFO = i and JOBZ = 'V', then the algorithm failed
!>                to compute an eigenvalue while working on the submatrix
!>                lying in rows and columns INFO/(N+1) through
!>                mod(INFO,N+1).
!>

so 0 = slay. negative = you passed a bad argument (the i-th one, specifically, exposed by INFO = -i 🙈). positive = the algorithm didn't converge, and the details depend on JOBZ, exactly as written above. no cap.

👑 Author 👑

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

four whole institutions, we love a collaborative moment 🫶

⭐ Further Details ⭐

Modified description of INFO. Sven, 16 Feb 05.

thanks Sven 💜

🧚 Contributors 🧚

  • Jeff Rutter, Computer Science Division, University of California at Berkeley, USA

shoutout Jeff, main character energy fr fr ✨

🌈 Further Details 🌈

the sequel section, and it's all the reading material:

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

three whole papers, read them and cite them, iykyk 📚

Definition at line 245 of file cheevd_2stage.f. 🎯

that's where she lives.

💖 Author (the meta one) 💖

Generated automatically by Doxygen for LAPACK from the source code.

not a human, just Doxygen doing Doxygen things 💅

and that's the page!! LAPACK, Version 3.12.0, dated SRC/cheevd_2stage.f(3) — generated automatically by Doxygen for LAPACK from the source code. bye bestie, go compute some eigenvalues, ily 🫶✨🎀
📦 where this page comes from