SRC/ssbevd_2stage.f(3)

📦

version 3.12.1 · 4 versions

3.12.1 · arch rolling (latest)
3.12.0 · opensuse-leap 16.0
3.9.0 · centos-stream 9
3.12.0 · centos-stream 10, fedora 43, fedora 44

✨ SRC/ssbevd_2stage.f ✨

okay bestie, so this is a page from the LAPACK Library Functions Manual, and it's all about one very specific little icon: ssbevd_2stage. it's giving "quiet genius subroutine that does a LOT" energy. let's get into it 💅

🦋 SYNOPSIS 🦋

Functions/Subroutines

subroutine ssbevd_2stage (jobz, uplo, n, kd, ab, ldab, w, z, ldz, work, lwork, iwork, liwork, info) — SSBEVD_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices

💖 Function/Subroutine Documentation 💖

`subroutine ssbevd_2stage (character jobz, character uplo, integer n, integer kd, real, dimension( ldab, * ) ab, integer ldab, real, dimension( * ) w, real, dimension( ldz, * ) z, integer ldz, real, dimension( * ) work, integer lwork, integer, dimension( * ) iwork, integer liwork, integer info)`

SSBEVD_2STAGE computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices. she said "OTHER matrices" and honestly, respect. 👑

🎀 Purpose:

SSBEVD_2STAGE computes all the eigenvalues and, optionally, eigenvectors of a real symmetric band matrix A using the 2stage technique for the reduction to tridiagonal. If eigenvectors are desired, it uses a divide and conquer algorithm.

like, she's out here doing the whole two-stage glow-up on a symmetric band matrix and then hitting it with divide and conquer if you want eigenvectors too. multi-talented fr fr 🌸

⭐ Parameters ⭐

JOBZ

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

so 'N' = eigenvalues only, and 'V' = eigenvalues and eigenvectors, but plot twist: 'V' is not available in this release 😭 so don't come for her, she said what she said.

UPLO

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

pick your triangle, bestie — 'U' for upper, 'L' for lower. that's it, that's the choice. 🦋

N

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

the order of matrix A, and she's gotta be N >= 0. no negatives, 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.

so it's the number of superdiagonals when UPLO = 'U', or the number of subdiagonals when UPLO = 'L'. and yes, KD >= 0 — mandatory. ✨

AB

AB is REAL array, dimension (LDAB, N) On entry, the upper or lower triangle of the symmetric 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.

okay so on entry this is where you stash the upper or lower triangle of the symmetric band matrix A, tucked into the first KD+1 rows of the array. the j-th column of A lives in the j-th column of AB like this:

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

and on exit? she's overwritten, bestie 💀 AB gets replaced by the values generated during the reduction to tridiagonal form. 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. iconic behaviour honestly.

LDAB

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

leading dimension of AB, and it's gotta be LDAB >= KD + 1. no shortcuts. 🎀

W

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

the eigenvalues, in ascending order, when INFO = 0. sorted and serving. ✨

Z

Z is REAL 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.

if JOBZ = 'V' and INFO = 0, Z is holding the orthonormal eigenvectors of A, with the i-th column of Z being the eigenvector that matches W(i). if JOBZ = 'N', Z is simply not referenced — she's off duty, don't @ 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).

WORK

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

on exit, if INFO = 0, then WORK(1) hands you the optimal LWORK. she's thoughtful like that. 💜

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 + N 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 and IWORK arrays, returns these values as the first entries of the WORK and IWORK arrays, and no error message related to LWORK or LIWORK is issued by XERBLA.

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

if JOBZ = 'N' and N > 1, LWORK must be queried, where

LWORK = MAX(1, dimension) where
dimension = (2KD+1)*N + KD*NTHREADS + N
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. 😭 (we been knew)

and if LWORK = -1, then a workspace query is assumed — she only calculates the optimal sizes of the WORK and IWORK arrays, returns them as the first entries of the WORK and IWORK arrays, and no error message related to LWORK or LIWORK is issued by XERBLA. so you get your info and zero nagging. 🫶

IWORK

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

dimension is (MAX(1,LIWORK)), and on exit, if INFO = 0, then IWORK(1) gives you the optimal LIWORK. ✨

LIWORK

LIWORK is INTEGER The dimension of the array IWORK. If JOBZ = 'N' or N <= 1, LIWORK must be at least 1. If JOBZ = 'V' and N > 2, 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 and IWORK arrays, returns these values as the first entries of the WORK and IWORK arrays, and no error message related to LWORK or LIWORK is issued by XERBLA.

the dimension of the IWORK array:

if JOBZ = 'N' or N <= 1, LIWORK must be at least 1
if JOBZ = 'V' and N > 2, LIWORK must be at least 3 + 5*N

and if LIWORK = -1, then a workspace query is assumed; the routine only calculates the optimal sizes of the WORK and IWORK arrays, returns those values as the first entries of the WORK and IWORK arrays, and no error message related to LWORK or LIWORK is issued by XERBLA. same deal as before, no cap. 💅

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.

= 0: successful exit 🎉
< 0: if INFO = -i, the i-th argument had an illegal value — someone passed something messy, not naming names
> 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.

the whole squad collaborated, we love a group project that actually worked. 🫶

🌈 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

like, if you want the FULL lore on the 2stage techniques, the receipts are all right there. academic citations ate, honestly. 📚🔥

Definition at line 226 of file ssbevd_2stage.f.

🌸 sign-off 🌸

this page was generated automatically by Doxygen for LAPACK from the source code, and it's from LAPACK Version 3.12.0. mwah, bye bestie 💖✨🎀

📦 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