SRC/zhbevd_2stage.f(3)

📦

version 3.12.1 · 7 versions

3.12.1 · arch rolling (latest)
3.9.0 · centos-stream 9
3.10.0 · ubuntu jammy
3.12.0 · ubuntu noble
3.12.0 · ubuntu noble
3.12.0 · centos-stream 10, fedora 43, fedora 44
3.11.0 · debian bookworm

💅 SRC/zhbevd_2stage.f — LAPACK manual page, bestie edition 🎀

okay so this is a page from the LAPACK Library Functions Manual, and it's about one very specific little icon: zhbevd_2stage. Buckle up, she's niche but she's powerful. ✨

✨ NAME ✨

SRC/zhbevd_2stage.f

that's it. that's the name. the file, the source, the whole vibe. iykyk. 💜

🦋 SYNOPSIS 🦋

Functions/Subroutines

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 — like, that's her whole job description and she's slaying it. 👑

🌸 Function/Subroutine Documentation 🌸

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)

okay so literally: ZHBEVD_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices. seventeen arguments, zero notes, she's booked and busy. 💀

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

so bestie, the tea is: she takes your complex Hermitian band matrix A, does the whole two-stage reduction-to-tridiagonal situation (that's the ✨2stage✨ part, main character energy), and if you want eigenvectors too she brings out the divide and conquer algorithm. lowkey iconic. 🫶

🔥 Parameters 🔥

JOBZ

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

'N' — eigenvalues only, minimal effort, respect honestly 🎀
'V' — eigenvalues and eigenvectors… except Not available in this release. 😭 so close bestie, so close.

UPLO

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

'U' — we're keeping the upper triangle of A, aesthetic
'L' — we're keeping the lower triangle of A, also aesthetic

N

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

N is the order of your matrix A, and the rule is N >= 0. no negatives, that's the boundary, periodt. 💅

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

KD = superdiagonals when UPLO = 'U', subdiagonals when UPLO = 'L'. and KD >= 0, always. she's a band queen, not a full-matrix queen. 👑

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

AB is a COMPLEX*16 array, dimension (LDAB, N).

On entry 🛬 — upper or lower triangle of the Hermitian band matrix A, chilling in the first KD+1 rows of the array. the j-th column of A lives in the j-th column of AB like:

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 the values generated during the reduction to tridiagonal form. so write down what you need first, it's giving "no take-backs". 💀 if UPLO = 'U', the first superdiagonal and the diagonal of the tridiagonal matrix T come back in rows KD and KD+1 of AB; if UPLO = 'L', the diagonal and first subdiagonal of T come back in the first two rows of AB. cute.

LDAB

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

leading dimension of AB, and the vibe check is LDAB >= KD + 1. that's it. ⭐

W

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

DOUBLE PRECISION, dimension (N). if INFO = 0, you get the eigenvalues in ascending order — sorted, tidy, organized, unlike my notes app. 😭

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

COMPLEX*16, dimension (LDZ, N). if JOBZ = 'V' and INFO = 0, Z holds the orthonormal eigenvectors of A, i-th column ↔ W(i). if JOBZ = 'N', Z is literally not referenced — she doesn't even look at her. 🙈

LDZ

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

leading dimension of Z. LDZ >= 1, and if JOBZ = 'V' then LDZ >= max(1,N). conditional rules, we love a structured queen. 🎀

WORK

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

COMPLEX*16, dimension (MAX(1,LWORK)). on exit, if INFO = 0, WORK(1) returns the optimal LWORK. she's a workspace scout, always reporting back. 🧚

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

LWORK is the length of WORK. LWORK >= 1 when N <= 1; otherwise:

if JOBZ = 'N' and N > 1, LWORK must be queried. the formula:
- 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 too. Not yet available. 😭

and if LWORK = -1, 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. she's asking, not telling. 💅

RWORK

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

DOUBLE PRECISION, dimension (LRWORK). on exit, if INFO = 0, RWORK(1) returns the optimal LRWORK. same energy, different array. 🔥

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

LRWORK is the dimension of RWORK. the minimums, bestie:

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

and if LRWORK = -1, a workspace query is assumed — same deal as before: she 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.
!>

INTEGER array, dimension (MAX(1,LIWORK)). on exit, if INFO = 0, IWORK(1) returns the optimal LIWORK. the third member of the workspace trio, always showing up. 💜

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

LIWORK is the dimension of 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 yes, if LIWORK = -1, a workspace query is assumed — she 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. three for three, consistent queen. 🌈

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 is the status report, and she keeps it real:

= 0 — successful exit, we ate, no crumbs 👑
< 0 — if INFO = -i, the i-th argument had an illegal value, someone's getting read 💀
> 0 — if INFO = i, the algorithm failed to converge; i off-diagonal elements of an intermediate tridiagonal form did not converge to zero. that's a genuine yikes 😭

🧚 Author

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

four institutions, one subroutine, we stan a collaborative moment. 🌸

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

if you want the full 2stage lore, it's all in these papers — citation slay, honestly. 📚✨

🎀 Definition

Definition at line 251 of file zhbevd_2stage.f.

💖 Sign-off

this page was Generated automatically by Doxygen for LAPACK from the source code — a robot wrote it, i just gave it the group-chat glow-up. 🫶

and that's the whole thing, bestie! LAPACK, Version 3.12.0, from SRC/zhbevd_2stage.f(3) — eigenvalues, bands, and workspace queries. go forth and compute. 👑💅✨

📦 where this page comes from

arch rolling: lapack-doc 3.12.1-2 · custom
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms