hpgv(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

💖 NAME 💖

hpgv — {hp,sp}gv: eig, QR iteration ✨

Okay bestie, this is the manual page for hpgv(3), and yes the name is a little cryptic — it's the family page for the {hp,sp}gv routines, and we're talking eig and QR iteration energy. Main character linear algebra. 💅

✨ SYNOPSIS ✨

🫶 Functions

  • subroutine chpgv (itype, jobz, uplo, n, ap, bp, w, z, ldz, work, rwork, info) — CHPGV
  • subroutine dspgv (itype, jobz, uplo, n, ap, bp, w, z, ldz, work, info) — DSPGV
  • subroutine sspgv (itype, jobz, uplo, n, ap, bp, w, z, ldz, work, info) — SSPGV
  • subroutine zhpgv (itype, jobz, uplo, n, ap, bp, w, z, ldz, work, rwork, info) — ZHPGV

🌸 Detailed Description 🌸

No cap, the actual good stuff lives down in Function Documentation — that's where each routine spills its whole story. Keep scrolling, babe. 👇

👑 Function Documentation 👑

🦋 subroutine chpgv (integer itype, character jobz, character uplo, integer n, complex, dimension( * ) ap, complex, dimension( * ) bp, real, dimension( * ) w, complex, dimension( ldz, * ) z, integer ldz, complex, dimension( * ) work, real, dimension( * ) rwork, integer info)

CHPGV

💜 Purpose:

!>
!> CHPGV computes all the eigenvalues and, optionally, the eigenvectors
!> of a complex generalized Hermitian-definite eigenproblem, of the form
!> A*x=(lambda)*B*x,  A*Bx=(lambda)*x,  or B*A*x=(lambda)*x.
!> Here A and B are assumed to be Hermitian, stored in packed format,
!> and B is also positive definite.
!>

So real talk: CHPGV gets you all the eigenvalues, and if you want, the eigenvectors too, for a complex generalized Hermitian-definite eigenproblem. 💖 A and B are Hermitian and they're chilling in packed format, and B is also positive definite (that part is not optional, bestie).

🎀 Parameters

  • ITYPE — It's an INTEGER, and it picks which flavor of problem you're solving:
!>          ITYPE is INTEGER
!>          Specifies the problem type to be solved:
!>          = 1:  A*x = (lambda)*B*x
!>          = 2:  A*B*x = (lambda)*x
!>          = 3:  B*A*x = (lambda)*x
!>
  • JOBZ — A CHARACTER*1, the "how much do you want" switch:
!>          JOBZ is CHARACTER*1
!>          = 'N':  Compute eigenvalues only;
!>          = 'V':  Compute eigenvalues and eigenvectors.
!>
  • UPLO — Also a CHARACTER*1, and it says which triangle of A and B you actually stored:
!>          UPLO is CHARACTER*1
!>          = 'U':  Upper triangles of A and B are stored;
!>          = 'L':  Lower triangles of A and B are stored.
!>
  • N — INTEGER, the order of the matrices A and B. Constraint: N >= 0.
  • AP — COMPLEX array, dimension (N*(N+1)/2). On entry it's the upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array — the j-th column of A lives in AP like this:
!>          AP is COMPLEX array, dimension (N*(N+1)/2)
!>          On entry, the upper or lower triangle of the Hermitian matrix
!>          A, packed columnwise in a linear array.  The j-th column of A
!>          is stored in the array AP as follows:
!>          if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
!>          if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.
!>
!>          On exit, the contents of AP are destroyed.
!>
Heads up: on exit the contents of AP are destroyed. Gone. Feral. Do not expect to read your A back out of there. 💀
  • BP — COMPLEX array, dimension (N*(N+1)/2). On entry it's the upper or lower triangle of the Hermitian matrix B, packed columnwise in a linear array — the j-th column of B is stored like so:
!>          BP is COMPLEX array, dimension (N*(N+1)/2)
!>          On entry, the upper or lower triangle of the Hermitian matrix
!>          B, packed columnwise in a linear array.  The j-th column of B
!>          is stored in the array BP as follows:
!>          if UPLO = 'U', BP(i + (j-1)*j/2) = B(i,j) for 1<=i<=j;
!>          if UPLO = 'L', BP(i + (j-1)*(2*n-j)/2) = B(i,j) for j<=i<=n.
!>
!>          On exit, the triangular factor U or L from the Cholesky
!>          factorization B = U**H*U or B = L*L**H, in the same storage
!>          format as B.
!>

So BP comes back holding the triangular factor U or L from the Cholesky factorization B = U**H*U or B = L*L**H, in the same storage format as B. She's transformed. 💅

  • W — REAL array, dimension (N). If INFO = 0, this is where the eigenvalues land, in ascending order. Slay. ✨
  • Z — COMPLEX array, dimension (LDZ, N). If JOBZ = 'V', then when INFO = 0, Z contains the matrix Z of eigenvectors, normalized like this:
!>          Z is COMPLEX array, dimension (LDZ, N)
!>          If JOBZ = 'V', then if INFO = 0, Z contains the matrix Z of
!>          eigenvectors.  The eigenvectors are normalized as follows:
!>          if ITYPE = 1 or 2, Z**H*B*Z = I;
!>          if ITYPE = 3, Z**H*inv(B)*Z = I.
!>          If JOBZ = 'N', then Z is not referenced.
!>

And if JOBZ = 'N'? Z is literally not referenced. She's not invited to the function. 🙈

  • LDZ — INTEGER, the leading dimension of the array Z. You need LDZ >= 1, and if JOBZ = 'V', then LDZ >= max(1,N).
  • WORK — COMPLEX array, dimension (max(1, 2*N-1)).
  • RWORK — REAL array, dimension (max(1, 3*N-2)).
  • INFO — INTEGER, the vibe check at the end:
!>          INFO is INTEGER
!>          = 0:  successful exit
!>          < 0:  if INFO = -i, the i-th argument had an illegal value
!>          > 0:  CPPTRF or CHPEV returned an error code:
!>             <= N:  if INFO = i, CHPEV failed to converge;
!>                    i off-diagonal elements of an intermediate
!>                    tridiagonal form did not convergeto zero;
!>             > N:   if INFO = N + i, for 1 <= i <= n, then the leading
!>                    principal minor of order i of B is not positive.
!>                    The factorization of B could not be completed and
!>                    no eigenvalues or eigenvectors were computed.
!>
Translation bestie: INFO = 0 is the win. INFO < 0 means argument number i was illegal. INFO > 0 means CPPTRF or CHPEV threw an error code — and if it's greater than N, the leading principal minor of order i of B is not positive, so the factorization of B couldn't be completed and no eigenvalues or eigenvectors were computed. Genuinely tragic. 😭

🌈 Author

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

⭐ Definition at line 163 of file chpgv.f.

🦋 subroutine dspgv (integer itype, character jobz, character uplo, integer n, double precision, dimension( * ) ap, double precision, dimension( * ) bp, double precision, dimension( * ) w, double precision, dimension( ldz, * ) z, integer ldz, double precision, dimension( * ) work, integer info)

DSPGV

💜 Purpose:

!>
!> DSPGV computes all the eigenvalues and, optionally, the eigenvectors
!> of a real generalized symmetric-definite eigenproblem, of the form
!> A*x=(lambda)*B*x,  A*Bx=(lambda)*x,  or B*A*x=(lambda)*x.
!> Here A and B are assumed to be symmetric, stored in packed format,
!> and B is also positive definite.
!>

Same energy as her complex sister, but make it real: DSPGV computes all the eigenvalues and, optionally, the eigenvectors of a real generalized symmetric-definite eigenproblem. A and B are symmetric, packed format, and B is positive definite. Periodt. 💅

🎀 Parameters

  • ITYPE — INTEGER, picks the problem type:
!>          ITYPE is INTEGER
!>          Specifies the problem type to be solved:
!>          = 1:  A*x = (lambda)*B*x
!>          = 2:  A*B*x = (lambda)*x
!>          = 3:  B*A*x = (lambda)*x
!>
  • JOBZ — CHARACTER*1:
!>          JOBZ is CHARACTER*1
!>          = 'N':  Compute eigenvalues only;
!>          = 'V':  Compute eigenvalues and eigenvectors.
!>
  • UPLO — CHARACTER*1, tells you which triangle is stored:
!>          UPLO is CHARACTER*1
!>          = 'U':  Upper triangles of A and B are stored;
!>          = 'L':  Lower triangles of A and B are stored.
!>
  • N — INTEGER, order of the matrices A and B. Constraint: N >= 0.
  • AP — DOUBLE PRECISION array, dimension (N*(N+1)/2). On entry, the upper or lower triangle of the symmetric matrix A, packed columnwise in a linear array. The j-th column of A goes into AP like this:
!>          AP is DOUBLE PRECISION array, dimension (N*(N+1)/2)
!>          On entry, the upper or lower triangle of the symmetric matrix
!>          A, packed columnwise in a linear array.  The j-th column of A
!>          is stored in the array AP as follows:
!>          if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
!>          if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.
!>
!>          On exit, the contents of AP are destroyed.
!>
Again for the people in the back: AP contents are destroyed on exit. Your A does not survive the function. 💀
  • BP — DOUBLE PRECISION array, dimension (N*(N+1)/2). On entry, the upper or lower triangle of the symmetric matrix B, packed columnwise in a linear array:
!>          BP is DOUBLE PRECISION array, dimension (N*(N+1)/2)
!>          On entry, the upper or lower triangle of the symmetric matrix
!>          B, packed columnwise in a linear array.  The j-th column of B
!>          is stored in the array BP as follows:
!>          if UPLO = 'U', BP(i + (j-1)*j/2) = B(i,j) for 1<=i<=j;
!>          if UPLO = 'L', BP(i + (j-1)*(2*n-j)/2) = B(i,j) for j<=i<=n.
!>
!>          On exit, the triangular factor U or L from the Cholesky
!>          factorization B = U**T*U or B = L*L**T, in the same storage
!>          format as B.
!>

On exit, BP holds the triangular factor U or L from the Cholesky factorization B = U**T*U or B = L*L**T, in the same storage format as B. Iconic. ✨

  • W — DOUBLE PRECISION array, dimension (N). If INFO = 0, the eigenvalues, in ascending order.
  • Z — DOUBLE PRECISION array, dimension (LDZ, N). If JOBZ = 'V' and INFO = 0, Z contains the matrix Z of eigenvectors, normalized like:
!>          Z is DOUBLE PRECISION array, dimension (LDZ, N)
!>          If JOBZ = 'V', then if INFO = 0, Z contains the matrix Z of
!>          eigenvectors.  The eigenvectors are normalized as follows:
!>          if ITYPE = 1 or 2, Z**T*B*Z = I;
!>          if ITYPE = 3, Z**T*inv(B)*Z = I.
!>          If JOBZ = 'N', then Z is not referenced.
!>

If JOBZ = 'N', Z is not referenced. Not even a little bit. 🙈

  • LDZ — INTEGER, leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', LDZ >= max(1,N).
  • WORK — DOUBLE PRECISION array, dimension (3*N).
  • INFO — INTEGER, the final verdict:
!>          INFO is INTEGER
!>          = 0:  successful exit
!>          < 0:  if INFO = -i, the i-th argument had an illegal value
!>          > 0:  DPPTRF or DSPEV returned an error code:
!>             <= N:  if INFO = i, DSPEV failed to converge;
!>                    i off-diagonal elements of an intermediate
!>                    tridiagonal form did not converge to zero.
!>             > N:   if INFO = n + i, for 1 <= i <= n, then the leading
!>                    principal minor of order i of B is not positive.
!>                    The factorization of B could not be completed and
!>                    no eigenvalues or eigenvectors were computed.
!>
Read this carefully bestie: INFO > N — meaning INFO = n + i for 1 <= i <= n — means the leading principal minor of order i of B is not positive, the factorization of B could not be completed, and no eigenvalues or eigenvectors were computed. Nothing. Nada. 😭

🌈 Author

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

⭐ Definition at line 158 of file dspgv.f.

🦋 subroutine sspgv (integer itype, character jobz, character uplo, integer n, real, dimension( * ) ap, real, dimension( * ) bp, real, dimension( * ) w, real, dimension( ldz, * ) z, integer ldz, real, dimension( * ) work, integer info)

SSPGV

💜 Purpose:

!>
!> SSPGV computes all the eigenvalues and, optionally, the eigenvectors
!> of a real generalized symmetric-definite eigenproblem, of the form
!> A*x=(lambda)*B*x,  A*Bx=(lambda)*x,  or B*A*x=(lambda)*x.
!> Here A and B are assumed to be symmetric, stored in packed format,
!> and B is also positive definite.
!>

SSPGV — single precision edition, but the same whole vibe. All the eigenvalues and, optionally, the eigenvectors of a real generalized symmetric-definite eigenproblem. A and B symmetric, packed format, B positive definite. She ate. 💅

🎀 Parameters

  • ITYPE — INTEGER, the problem type selector:
!>          ITYPE is INTEGER
!>          Specifies the problem type to be solved:
!>          = 1:  A*x = (lambda)*B*x
!>          = 2:  A*B*x = (lambda)*x
!>          = 3:  B*A*x = (lambda)*x
!>
  • JOBZ — CHARACTER*1, eigenvalues only or eigenvalues and eigenvectors:
!>          JOBZ is CHARACTER*1
!>          = 'N':  Compute eigenvalues only;
!>          = 'V':  Compute eigenvalues and eigenvectors.
!>
  • UPLO — CHARACTER*1, which triangles of A and B you stored:
!>          UPLO is CHARACTER*1
!>          = 'U':  Upper triangles of A and B are stored;
!>          = 'L':  Lower triangles of A and B are stored.
!>
  • N — INTEGER, the order of the matrices A and B. Constraint: N >= 0.
  • AP — REAL array, dimension (N*(N+1)/2) — and bestie, this is exactly where our part 1 dips…

AP 🎀 — REAL array, dimension (N*(N+1)/2)

On entry, this is the upper or lower triangle of the symmetric matrix A, packed columnwise in a linear array. The j-th column of A lives in AP like this:

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.
⚠️ On exit, the contents of AP are destroyed. Like, gone gone. If you needed that matrix afterwards bestie… you didn't. Copy it first, iykyk 😭

BP 🦋 — REAL array, dimension (N*(N+1)/2)

On entry, the upper or lower triangle of the symmetric matrix B, packed columnwise in a linear array. The j-th column of B is stored in BP as:

if UPLO = 'U', BP(i + (j-1)*j/2) = B(i,j) for 1<=i<=j;
if UPLO = 'L', BP(i + (j-1)*(2*n-j)/2) = B(i,j) for j<=i<=n.

On exit, BP holds the triangular factor U or L from the Cholesky factorization B = U**T*U or B = L*L**T, in the same storage format as B. So it's not destroyed, it's transformed — main character energy honestly 💅

W ⭐ — REAL array, dimension (N)

If INFO = 0, this is where the eigenvalues live, in ascending order. Cutest array on the page tbh.

Z 🌸 — REAL array, dimension (LDZ, N)

If JOBZ = 'V', then if INFO = 0, Z contains the matrix Z of eigenvectors. The eigenvectors are normalized like so:

if ITYPE = 1 or 2, Z**T*B*Z = I;
if ITYPE = 3, Z**T*inv(B)*Z = I.

If JOBZ = 'N', then Z is not referenced at all. It's just vibing. Not invited to the function.

LDZ 📏 — INTEGER

The leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', then LDZ >= max(1,N). Respect the constraint or catch an error, periodt.

WORK 🔧 — REAL array, dimension (3*N)

Scratch space. That's it. That's the whole description. Iconic brevity.

INFO 💀 — INTEGER

  • = 0: successful exit 🎉
  • < 0: if INFO = -i, the i-th argument had an illegal value. Something you passed in was not it.
  • > 0: SPPTRF or SSPEV returned an error code:
    • <= N: if INFO = i, SSPEV failed to converge; i off-diagonal elements of an intermediate tridiagonal form did not converge to zero.
    • > N: if INFO = n + i, for 1 <= i <= n, then the leading principal minor of order i of B is not positive. The factorization of B could not be completed and no eigenvalues or eigenvectors were computed. Basically B wasn't positive definite and the whole thing said "nope" 🫠

Author ✍️

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

Definition at line 158 of file sspgv.f.

Okay so now the complex twin, and she is serving the exact same energy but with more letters and more work arrays 👑

subroutine zhpgv (integer itype, character jobz, character uplo, integer n,
    complex*16, dimension( * ) ap, complex*16, dimension( * ) bp, double
    precision, dimension( * ) w, complex*16, dimension( ldz, * ) z, integer
    ldz, complex*16, dimension( * ) work, double precision, dimension( * )
    rwork, integer info)

ZHPGV 💜

Purpose 🎯

ZHPGV computes all the eigenvalues and, optionally, the eigenvectors of a complex generalized Hermitian-definite eigenproblem, of the form:

A*x=(lambda)*B*x,  A*Bx=(lambda)*x,  or B*A*x=(lambda)*x.

Here A and B are assumed to be Hermitian, stored in packed format, and B is also positive definite. B has to be positive definite, that's not optional, that's the whole vibe check.

Parameters 🧾

ITYPE — INTEGER

Specifies the problem type to be solved:

  • = 1: A*x = (lambda)*B*x
  • = 2: A*B*x = (lambda)*x
  • = 3: B*A*x = (lambda)*x

JOBZ — CHARACTER*1

  • = 'N': Compute eigenvalues only;
  • = 'V': Compute eigenvalues and eigenvectors.

UPLO — CHARACTER*1

  • = 'U': Upper triangles of A and B are stored;
  • = 'L': Lower triangles of A and B are stored.

N — INTEGER

The order of the matrices A and B. N >= 0. Zero is allowed, bestie, it's a valid order, don't be weird about it.

AP 🌈 — COMPLEX*16 array, dimension (N*(N+1)/2)

On entry, the upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:

if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.
⚠️ On exit, the contents of AP are destroyed. Same deal as her real-valued sister. Say bye to your input 😭

BP 🍓 — COMPLEX*16 array, dimension (N*(N+1)/2)

On entry, the upper or lower triangle of the Hermitian matrix B, packed columnwise in a linear array. The j-th column of B is stored in BP as follows:

if UPLO = 'U', BP(i + (j-1)*j/2) = B(i,j) for 1<=i<=j;
if UPLO = 'L', BP(i + (j-1)*(2*n-j)/2) = B(i,j) for j<=i<=n.

On exit, the triangular factor U or L from the Cholesky factorization B = U**H*U or B = L*L**H, in the same storage format as B. Note the **H — we're in conjugate transpose territory now, she's fancy 💅

W ⭐ — DOUBLE PRECISION array, dimension (N)

If INFO = 0, the eigenvalues in ascending order.

Z 🦋 — COMPLEX*16 array, dimension (LDZ, N)

If JOBZ = 'V', then if INFO = 0, Z contains the matrix Z of eigenvectors. The eigenvectors are normalized as follows:

if ITYPE = 1 or 2, Z**H*B*Z = I;
if ITYPE = 3, Z**H*inv(B)*Z = I.

If JOBZ = 'N', then Z is not referenced. She's off the clock 🫶

LDZ 📏 — INTEGER

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

WORK 🔧 — COMPLEX*16 array, dimension (max(1, 2*N-1))

Scratch space, complex edition ✨

RWORK 🧚 — DOUBLE PRECISION array, dimension (max(1, 3*N-2))

More scratch space, but real this time. Yes you need both. No you can't skip it. That's just how ZHPGV rolls.

INFO 💀 — INTEGER

  • = 0: successful exit 🎉
  • < 0: if INFO = -i, the i-th argument had an illegal value.
  • > 0: ZPPTRF or ZHPEV returned an error code:
    • <= N: if INFO = i, ZHPEV failed to converge; i off-diagonal elements of an intermediate tridiagonal form did not converge to zero (the source code literally spells it convergeto — we stan a typo, no cap 🙈);
    • > N: if INFO = N + i, for 1 <= i <= n, then the leading principal minor of order i of B is not positive. The factorization of B could not be completed and no eigenvalues or eigenvectors were computed.

Author ✍️

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

Definition at line 163 of file zhpgv.f.

Author ✍️ (yes, again, it's a whole section)

Generated automatically by Doxygen for LAPACK from the source code. A bot wrote this and honestly it ate 🤖✨

And that's the whole page bestie, we did it 💖 This was LAPACK Version 3.12.0, page hpgv(3) — go forth, pack those triangles, and don't forget that AP gets destroyed on exit. Mwah 💋

📦 where this page comes from