stevx(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

👑 stevx(3) — Library Functions Manual ✨

okay bestie, welcome to stevx (manual page stevx(3), from the Library Functions Manual) — literally the page that says stevx - stevx: eig, bisection. yes that's the whole NAME line, she's mysterious like that 💅

🎀 NAME

stevx — stevx: eig, bisection

✨ SYNOPSIS

🌸 Functions

  • subroutine dstevx (jobz, range, n, d, e, vl, vu, il, iu, abstol, m, w, z, ldz, work, iwork, ifail, info) — DSTEVX computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices
  • subroutine sstevx (jobz, range, n, d, e, vl, vu, il, iu, abstol, m, w, z, ldz, work, iwork, ifail, info) — SSTEVX computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices

🦋 Detailed Description

(this section is lowkey just the header, no tea here — the real content is under Function Documentation, keep scrolling bestie)

💖 Function Documentation

🧚 subroutine dstevx

subroutine dstevx (character jobz, character range, integer n, double
    precision, dimension( * ) d, double precision, dimension( * ) e, double
    precision vl, double precision vu, integer il, integer iu, double
    precision abstol, integer m, double precision, dimension( * ) w, double
    precision, dimension( ldz, * ) z, integer ldz, double precision,
    dimension( * ) work, integer, dimension( * ) iwork, integer, dimension(
    * ) ifail, integer info)

DSTEVX computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices

⭐ Purpose:

!>
!> DSTEVX computes selected eigenvalues and, optionally, eigenvectors
!> of a real symmetric tridiagonal matrix A.  Eigenvalues and
!> eigenvectors can be selected by specifying either a range of values
!> or a range of indices for the desired eigenvalues.
!>

🔥 Parameters

  • JOBZ
!>          JOBZ is CHARACTER*1
!>          = 'N':  Compute eigenvalues only;
!>          = 'V':  Compute eigenvalues and eigenvectors.
!>
  • 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.
!>
  • N
!>          N is INTEGER
!>          The order of the matrix.  N >= 0.
!>
  • D
!>          D is DOUBLE PRECISION array, dimension (N)
!>          On entry, the n diagonal elements of the tridiagonal matrix
!>          A.
!>          On exit, D may be multiplied by a constant factor chosen
!>          to avoid over/underflow in computing the eigenvalues.
!>
  • E
!>          E is DOUBLE PRECISION array, dimension (max(1,N-1))
!>          On entry, the (n-1) subdiagonal elements of the tridiagonal
!>          matrix A in elements 1 to N-1 of E.
!>          On exit, E may be multiplied by a constant factor chosen
!>          to avoid over/underflow in computing the eigenvalues.
!>
  • 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'.
!>
  • 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.
!>
!>          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.
!>
  • 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)
!>          The first M elements contain the selected eigenvalues in
!>          ascending order.
!>
  • Z
!>          Z is DOUBLE PRECISION 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 (INFO > 0), 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.
!>
  • LDZ
!>          LDZ is INTEGER
!>          The leading dimension of the array Z.  LDZ >= 1, and if
!>          JOBZ = 'V', LDZ >= max(1,N).
!>
  • WORK
!>          WORK is DOUBLE PRECISION array, dimension (5*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.
!>
  • 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.

Definition at line 225 of file dstevx.f.

🫶 subroutine sstevx

subroutine sstevx (character jobz, character range, integer n, real,
    dimension( * ) d, real, dimension( * ) e, real vl, real vu, integer il,
    integer iu, real abstol, integer m, real, dimension( * ) w, real,
    dimension( ldz, * ) z, integer ldz, real, dimension( * ) work, integer,
    dimension( * ) iwork, integer, dimension( * ) ifail, integer info)

SSTEVX computes the eigenvalues and, optionally, the left and/or right eigenvectors for OTHER matrices

⭐ Purpose:

!>
!> SSTEVX computes selected eigenvalues and, optionally, eigenvectors
!> of a real symmetric tridiagonal matrix A.  Eigenvalues and
!> eigenvectors can be selected by specifying either a range of values
!> or a range of indices for the desired eigenvalues.
!>

🔥 Parameters

  • JOBZ
!>          JOBZ is CHARACTER*1
!>          = 'N':  Compute eigenvalues only;
!>          = 'V':  Compute eigenvalues and eigenvectors.
!>
  • 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.
!>
  • N
!>          N is INTEGER
!>          The order of the matrix.  N >= 0.
!>
  • D
!>          D is REAL array, dimension (N)
!>          On entry, the n diagonal elements of the tridiagonal matrix
!>          A.
!>          On exit, D may be multiplied by a constant factor chosen
!>          to avoid over/underflow in computing the eigenvalues.
!>
  • E
!>          E is REAL array, dimension (max(1,N-1))
!>          On entry, the (n-1) subdiagonal elements of the tridiagonal
!>          matrix A in elements 1 to N-1 of E.
!>          On exit, E may be multiplied by a constant factor chosen
!>          to avoid over/underflow in computing the eigenvalues.
!>
  • VL
!>          VL is REAL
!>          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 REAL
!>          If RANGE='V', the upper bound of the interval to
!>          be searched for eigenvalues. VL < VU.
!>          Not referenced if RANGE = 'A' or 'I'.
!>
  • 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

ABSTOL is REAL — it's your absolute error tolerance for the eigenvalues, bestie. An approximate eigenvalue gets the green light as "converged" when it's determined to lie in an interval [a,b] whose width is less than or equal to

ABSTOL + EPS *   max( |a|,|b| ) ,

where EPS is the machine precision. And if ABSTOL is less than or equal to zero, then EPS*|T| gets used in its place instead, where |T| is the 1-norm of the tridiagonal matrix. 💅

Eigenvalues will be computed most accurately when ABSTOL is set to twice the underflow threshold 2*SLAMCH('S') — not zero, okay? Not zero. And if this routine comes back with INFO>0, which means some eigenvectors did not converge, try setting ABSTOL to 2*SLAMCH('S'). 🫶

See the write-up by Demmel and Kahan, LAPACK Working Note #3.

✨ M

M is INTEGER — the total number of eigenvalues found. 0 <= M <= N. If RANGE = 'A', then M = N, and if RANGE = 'I', then M = IU-IL+1. Math is mathing. 🧮

🎀 W

W is REAL array, dimension (N). The first M elements contain the selected eigenvalues in ascending order. Sorted, organized, main character energy. 👑

🦋 Z

Z is REAL 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 (INFO > 0), 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 at all, she's off duty. 💀

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. So budget extra columns, bestie, it's giving "pack a bigger suitcase". 🧳

🌈 LDZ

LDZ is INTEGER — the leading dimension of the array Z. LDZ >= 1, and if JOBZ = 'V', LDZ >= max(1,N). No cap. 🚫🧢

⭐ WORK

WORK is REAL array, dimension (5*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 said "not my section, not my problem". 🙈

🔥 INFO

INFO is INTEGER:

  • = 0: successful exit. slay. ✨
  • < 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.

Definition at line 225 of file sstevx.f.

💖 AUTHOR

Generated automatically by Doxygen for LAPACK from the source code.

okay that's the whole page, bestie — we ate and left no crumbs 🍽️💅 This was LAPACK, Version 3.12.0, in the stevx(3) era, and that's the vibe check complete. 🎀✨🦋

📦 where this page comes from