gees(3)

✨ NAME ✨

Okay bestie, welcome to gees(3) β€” literally the Schur form page, and it's giving iconic numerical linear algebra energy. The function is gees, and the one-liner is: gees β€” gees: Schur form. No cap, that's the whole name vibe. πŸ’…


πŸŽ€ SYNOPSIS πŸŽ€

πŸ’– Functions πŸ’–

⭐ cgees ⭐

subroutine cgees (jobvs, sort, select, n, a, lda, sdim, w, vs, ldvs,
    work, lwork, rwork, bwork, info)

CGEES computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices.

⭐ dgees ⭐

subroutine dgees (jobvs, sort, select, n, a, lda, sdim, wr, wi, vs,
    ldvs, work, lwork, bwork, info)

DGEES computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices.

⭐ sgees ⭐

subroutine sgees (jobvs, sort, select, n, a, lda, sdim, wr, wi, vs,
    ldvs, work, lwork, bwork, info)

SGEES computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices.

⭐ zgees ⭐

subroutine zgees (jobvs, sort, select, n, a, lda, sdim, w, vs, ldvs,
    work, lwork, rwork, bwork, info)

ZGEES computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices.


πŸ¦‹ Detailed Description πŸ¦‹

This section is lowkey just a runway to the function docs, bestie. The real detail is in the Function Documentation section right below. Let's go. ✨


🌸 Function Documentation 🌸

πŸ’œ cgees πŸ’œ

subroutine cgees (character jobvs, character sort, external select, integer
    n, complex, dimension( lda, * ) a, integer lda, integer sdim, complex,
    dimension( * ) w, complex, dimension( ldvs, * ) vs, integer ldvs,
    complex, dimension( * ) work, integer lwork, real, dimension( * ) rwork,
    logical, dimension( * ) bwork, integer info)

CGEES computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices.

🎯 Purpose 🎯

Okay so CGEES is the complex one, and here's the tea: for an N-by-N complex nonsymmetric matrix A, it computes the eigenvalues, the Schur form T, and β€” optionally β€” the matrix of Schur vectors Z. That gives you the Schur factorization A = Z*T*(Z**H). Iconic. ✨

If you want, it also orders the eigenvalues on the diagonal of the Schur form so the selected eigenvalues are at the top left. The leading columns of Z then form an orthonormal basis for the invariant subspace corresponding to those selected eigenvalues. Slay. πŸ’…

And real quick: a complex matrix is in Schur form if it is upper triangular. Periodt.

🧚 Parameters 🧚

  • JOBVS is CHARACTER*1:
    • = 'N': Schur vectors are not computed;
    • = 'V': Schur vectors are computed.
  • SORT is CHARACTER*1 and specifies whether or not to order the eigenvalues on the diagonal of the Schur form:
    • = 'N': Eigenvalues are not ordered:
    • = 'S': Eigenvalues are ordered (see SELECT).
  • SELECT is a LOGICAL FUNCTION of one COMPLEX argument.
    • SELECT must be declared EXTERNAL in the calling subroutine.
    • If SORT = 'S', SELECT is used to select eigenvalues to order to the top left of the Schur form.
    • If SORT = 'N', SELECT is not referenced.
    • The eigenvalue W(j) is selected if SELECT(W(j)) is true.
  • N is INTEGER β€” the order of the matrix A. N >= 0.
  • A is COMPLEX array, dimension (LDA,N).
    • On entry, the N-by-N matrix A.
    • On exit, A has been overwritten by its Schur form T.
  • LDA is INTEGER β€” the leading dimension of the array A. LDA >= max(1,N).
  • SDIM is INTEGER.
    • If SORT = 'N', SDIM = 0.
    • If SORT = 'S', SDIM = number of eigenvalues for which SELECT is true.
  • W is COMPLEX array, dimension (N).
    • W contains the computed eigenvalues, in the same order that they appear on the diagonal of the output Schur form T.
  • VS is COMPLEX array, dimension (LDVS,N).
    • If JOBVS = 'V', VS contains the unitary matrix Z of Schur vectors.
    • If JOBVS = 'N', VS is not referenced.
  • LDVS is INTEGER β€” the leading dimension of the array VS. LDVS >= 1; if JOBVS = 'V', LDVS >= N.
  • WORK is COMPLEX array, dimension (MAX(1,LWORK)).
    • On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  • LWORK is INTEGER β€” the dimension of the array WORK. LWORK >= max(1,2*N).
    • For good performance, LWORK must generally be larger.
    • If LWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA.
  • RWORK is REAL array, dimension (N).
  • BWORK is LOGICAL array, dimension (N).
    • Not referenced if SORT = 'N'.
  • INFO is INTEGER:
    • = 0: successful exit
    • < 0: if INFO = -i, the i-th argument had an illegal value.
    • > 0: if INFO = i, and i is
      • <= N: the QR algorithm failed to compute all the eigenvalues; elements 1:ILO-1 and i+1:N of W contain those eigenvalues which have converged; if JOBVS = 'V', VS contains the matrix which reduces A to its partially converged Schur form.
      • = N+1: the eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned);
      • = N+2: after reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the Schur form no longer satisfy SELECT = .TRUE.. This could also be caused by underflow due to scaling.

πŸ‘‘ Author πŸ‘‘

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Definition at line 195 of file cgees.f.


πŸ’™ dgees πŸ’™

subroutine dgees (character jobvs, character sort, external select, integer
    n, double precision, dimension( lda, * ) a, integer lda, integer sdim,
    double precision, dimension( * ) wr, double precision, dimension( * )
    wi, double precision, dimension( ldvs, * ) vs, integer ldvs, double
    precision, dimension( * ) work, integer lwork, logical, dimension( * )
    bwork, integer info)

DGEES computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices.

🎯 Purpose 🎯

DGEES is the real nonsymmetric version, bestie. For an N-by-N real nonsymmetric matrix A, it computes the eigenvalues, the real Schur form T, and β€” optionally β€” the matrix of Schur vectors Z. That's the Schur factorization A = Z*T*(Z**T). No cap. 🌈

It can also order the eigenvalues on the diagonal of the real Schur form so selected eigenvalues are at the top left. The leading columns of Z then form an orthonormal basis for the invariant subspace corresponding to the selected eigenvalues. Obsessed. 🫢

A matrix is in real Schur form if it is upper quasi-triangular with 1-by-1 and 2-by-2 blocks. The 2-by-2 blocks get standardized in the form

[  a  b  ]
[  c  a  ]

where b*c < 0. The eigenvalues of such a block are a +- sqrt(bc). Cute. πŸŽ€

🧚 Parameters 🧚

  • JOBVS is CHARACTER*1:
    • = 'N': Schur vectors are not computed;
    • = 'V': Schur vectors are computed.
  • SORT is CHARACTER*1 and specifies whether or not to order the eigenvalues on the diagonal of the Schur form:
    • = 'N': Eigenvalues are not ordered;
    • = 'S': Eigenvalues are ordered (see SELECT).
  • SELECT is a LOGICAL FUNCTION of two DOUBLE PRECISION arguments.
    • SELECT must be declared EXTERNAL in the calling subroutine.
    • If SORT = 'S', SELECT is used to select eigenvalues to sort to the top left of the Schur form.
    • If SORT = 'N', SELECT is not referenced.
    • An eigenvalue WR(j)+sqrt(-1)*WI(j) is selected if SELECT(WR(j),WI(j)) is true; i.e., if either one of a complex conjugate pair of eigenvalues is selected, then both complex eigenvalues are selected.
    • Note that a selected complex eigenvalue may no longer satisfy SELECT(WR(j),WI(j)) = .TRUE. after ordering, since ordering may change the value of complex eigenvalues (especially if the eigenvalue is ill-conditioned); in this case INFO is set to N+2 (see INFO below).
  • N is INTEGER β€” the order of the matrix A. N >= 0.
  • A is DOUBLE PRECISION array, dimension (LDA,N).
    • On entry, the N-by-N matrix A.
    • On exit, A has been overwritten by its real Schur form T.
  • LDA is INTEGER β€” the leading dimension of the array A. LDA >= max(1,N).
  • SDIM is INTEGER.
    • If SORT = 'N', SDIM = 0.
    • If SORT = 'S', SDIM = number of eigenvalues (after sorting) for which SELECT is true. (Complex conjugate pairs for which SELECT is true for either eigenvalue count as 2.)
  • WR is DOUBLE PRECISION array, dimension (N).
  • WI is DOUBLE PRECISION array, dimension (N).
    • WR and WI contain the real and imaginary parts, respectively, of the computed eigenvalues in the same order that they appear on the diagonal of the output Schur form T.
    • Complex conjugate pairs of eigenvalues will appear consecutively with the eigenvalue having the positive imaginary part first.
  • VS β€” DOUBLE PRECISION array, dimension (LDVS,N). Bestie, this is your Schur vector drop-off point ✨ If JOBVS = 'V', VS contains the orthogonal matrix Z of Schur vectors. If JOBVS = 'N', VS is literally not referenced β€” she's off the invite list, no hard feelings 🫢
  • LDVS β€” INTEGER. The leading dimension of the array VS. LDVS >= 1; and if JOBVS = 'V', then LDVS >= N. Respect the dimension rules or she WILL be mad πŸ’…
  • WORK β€” DOUBLE PRECISION array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) contains the optimal LWORK. It's giving "receipts on the way out" 🧾
  • LWORK β€” INTEGER. The dimension of the array WORK. LWORK >= max(1,3*N). For good performance, LWORK must generally be larger β€” ngl she'll run, but she'll be sluggish, and nobody wants that 🌸

Also, if LWORK = -1, then a workspace query is assumed: the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. Peak "just asking for a friend" energy, lowkey iconic πŸ’–

  • BWORK β€” LOGICAL array, dimension (N). Not referenced if SORT = 'N' β€” she's literally just vibing in the corner πŸ™ˆ
  • INFO β€” INTEGER. The whole mood report, fr fr:
    • = 0: successful exit. Slay. We ate πŸ‘‘
    • < 0: if INFO = -i, the i-th argument had an illegal value. Someone did NOT read the rules 😭
    • > 0: if INFO = i, and i is:
      • <= N: the QR algorithm failed to compute all the eigenvalues; elements 1:ILO-1 and i+1:N of WR and WI contain those eigenvalues which have converged; if JOBVS = 'V', VS contains the matrix which reduces A to its partially converged Schur form. Half-finished era πŸ’€
      • = N+1: the eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned). They're too close, bestie, it's complicated πŸ₯€
      • = N+2: after reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the Schur form no longer satisfy SELECT=.TRUE.. This could also be caused by underflow due to scaling. Roundoff said "not today" πŸ™ƒ

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Definition at line 214 of file dgees.f.


subroutine sgees

subroutine sgees (character jobvs, character sort, external select, integer
    n, real, dimension( lda, * ) a, integer lda, integer sdim, real,
    dimension( * ) wr, real, dimension( * ) wi, real, dimension( ldvs, * )
    vs, integer ldvs, real, dimension( * ) work, integer lwork, logical,
    dimension( * ) bwork, integer info)

SGEES computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices πŸŒˆπŸ’«

Purpose:

Okay so picture this πŸ‘‡

SGEES computes, for an N-by-N real nonsymmetric matrix A, the eigenvalues, the real Schur form T, and, optionally, the matrix of Schur vectors Z. This gives the Schur factorization A = Z*T*(Z**T). Iconic factorization behavior, no notes πŸ’…

Optionally, it also orders the eigenvalues on the diagonal of the real Schur form so that selected eigenvalues are at the top left. The leading columns of Z then form an orthonormal basis for the invariant subspace corresponding to the selected eigenvalues. Main character eigenvalues get the best seats in the house πŸ‘‘

A matrix is in real Schur form if it is upper quasi-triangular with 1-by-1 and 2-by-2 blocks. The 2-by-2 blocks will be standardized in the form

[  a  b  ]
[  c  a  ]

where b*c < 0. The eigenvalues of such a block are a +- sqrt(bc). Tiny block, big feelings πŸŽ€

Parameters

  • JOBVS β€” CHARACTER*1. Are we doing Schur vectors or not, bestie?
    • = 'N': Schur vectors are not computed.
    • = 'V': Schur vectors are computed. Let's goooo πŸ’–
  • SORT β€” CHARACTER*1. Specifies whether or not to order the eigenvalues on the diagonal of the Schur form.
    • = 'N': Eigenvalues are not ordered.
    • = 'S': Eigenvalues are ordered (see SELECT). Aesthetic diagonal, we love to see it ✨
  • SELECT β€” SELECT is a LOGICAL FUNCTION of two REAL arguments. SELECT must be declared EXTERNAL in the calling subroutine β€” don't forget, this is a whole thing, it will not work otherwise 😀
    • If SORT = 'S', SELECT is used to select eigenvalues to sort to the top left of the Schur form.
    • If SORT = 'N', SELECT is not referenced.
    • An eigenvalue WR(j)+sqrt(-1)*WI(j) is selected if SELECT(WR(j),WI(j)) is true; i.e., if either one of a complex conjugate pair of eigenvalues is selected, then both complex eigenvalues are selected. Package deal, no splitting the pair 🫢
    • Note that a selected complex eigenvalue may no longer satisfy SELECT(WR(j),WI(j)) = .TRUE. after ordering, since ordering may change the value of complex eigenvalues (especially if the eigenvalue is ill-conditioned); in this case INFO is set to N+2 (see INFO below). The vibes shifted mid-reorder, it happens 😭
  • N β€” INTEGER. The order of the matrix A. N >= 0. Zero is allowed, she's just small πŸ’•
  • A β€” REAL array, dimension (LDA,N). On entry, the N-by-N matrix A. On exit, A has been overwritten by its real Schur form T. She was transformed, glow-up complete 🌸
  • LDA β€” INTEGER. The leading dimension of the array A. LDA >= max(1,N). Rules are rules, bestie πŸ’…
  • SDIM β€” INTEGER. The selected-count check-in:
    • If SORT = 'N', SDIM = 0.
    • If SORT = 'S', SDIM = number of eigenvalues (after sorting) for which SELECT is true. (Complex conjugate pairs for which SELECT is true for either eigenvalue count as 2.) Both halves count, that's the rule, periodt πŸ‘‘
  • WR β€” REAL array, dimension (N).
  • WI β€” REAL array, dimension (N). WR and WI contain the real and imaginary parts, respectively, of the computed eigenvalues in the same order that they appear on the diagonal of the output Schur form T. Complex conjugate pairs of eigenvalues will appear consecutively with the eigenvalue having the positive imaginary part first. Positivity first, she's an optimist ✨
  • VS β€” REAL array, dimension (LDVS,N). If JOBVS = 'V', VS contains the orthogonal matrix Z of Schur vectors. If JOBVS = 'N', VS is not referenced. Living rent-free, unreferenced πŸ¦‹
  • LDVS β€” INTEGER. The leading dimension of the array VS. LDVS >= 1; if JOBVS = 'V', LDVS >= N. Bestie, check it twice πŸ”
  • WORK β€” REAL array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) contains the optimal LWORK. Receipts, as promised 🧾
  • LWORK β€” INTEGER. The dimension of the array WORK. LWORK >= max(1,3*N). For good performance, LWORK must generally be larger. Give her room to breathe πŸŽ€

Also, if LWORK = -1, then a workspace query is assumed: the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. Speedrun mode, zero scolding πŸ’«

  • BWORK β€” LOGICAL array, dimension (N). Not referenced if SORT = 'N' β€” she's unbothered, moisturized πŸ™ˆ
  • INFO β€” INTEGER. The full story:
    • = 0: successful exit. We did it, bestie πŸ‘‘
    • < 0: if INFO = -i, the i-th argument had an illegal value. Somebody skipped the syllabus 😭
    • > 0: if INFO = i, and i is:
      • <= N: the QR algorithm failed to compute all the eigenvalues; elements 1:ILO-1 and i+1:N of WR and WI contain those eigenvalues which have converged; if JOBVS = 'V', VS contains the matrix which reduces A to its partially converged Schur form. Partial convergence era, we've all been there πŸ’€
      • = N+1: the eigenvalues could not be reordered because some eigenvalues were too close to separate (the problem is very ill-conditioned). Too close, too messy, red flag πŸ₯€
      • = N+2: after reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the Schur form no longer satisfy SELECT=.TRUE.. This could also be caused by underflow due to scaling. Roundoff hijacked the playlist πŸ™ƒ

Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

Definition at line 214 of file sgees.f.


subroutine zgees

subroutine zgees (character jobvs, character sort, external select, integer
    n, complex*16, dimension( lda, * ) a, integer lda, integer sdim,
    complex*16, dimension( * ) w, complex*16, dimension( ldvs, * ) vs,
    integer ldvs, complex*16, dimension( * ) work, integer lwork, double
    precision, dimension( * ) rwork, logical, dimension( * ) bwork, integer
    info)

ZGEES computes the eigenvalues, the Schur form, and, optionally, the matrix of Schur vectors for GE matrices πŸŒˆπŸ’«

Purpose:

ZGEES computes, for an N-by-N complex nonsymmetric matrix A, the eigenvalues, the Schur form T, and, optionally, the matrix of Schur vectors Z. This gives the Schur factorization A = Z*T*(Z**H). Note the **H β€” complex edition hits different πŸ’œ

Optionally, it also orders the eigenvalues on the diagonal of the Schur form so that selected eigenvalues are at the top left. The leading columns of Z then form an orthonormal basis for the invariant subspace corresponding to the selected eigenvalues. Front-row seats for the chosen ones πŸ‘‘

A complex matrix is in Schur form if it is upper triangular. Simple as that β€” no 2-by-2 block drama over here, we're complex, we're clean, we're slaying ✨

Parameters

  • JOBVS β€” CHARACTER*1. Schur vectors: in or out?
    • = 'N': Schur vectors are not computed.
    • = 'V': Schur vectors are computed. Say less, we're computing πŸ’…
  • SORT β€” CHARACTER*1. Specifies whether or not to order the eigenvalues on the diagonal of the Schur form.
    • = 'N': Eigenvalues are not ordered:
    • = 'S': Eigenvalues are ordered (see SELECT). Organized queen behavior 🌸
  • SELECT β€”

SELECT πŸ’…

okay so SELECT is a LOGICAL FUNCTION of one COMPLEX*16 argument, and bestie, you have to declare it EXTERNAL in the calling subroutine or it will simply not work, no cap.

  • if SORT = 'S', SELECT is literally the thing used to pick which eigenvalues get ordered to the top left of the Schur form πŸŽ€
  • if SORT = 'N', SELECT is not referenced β€” she's off duty, don't worry abt her πŸ™ˆ
  • the eigenvalue W(j) gets selected if SELECT(W(j)) is true. that's it, that's the whole vibe check ✨

N πŸ¦‹

N is INTEGER β€” the order of the matrix A. and N >= 0. be normal abt it πŸ’–

A 🌸

A is a COMPLEX*16 array, dimension (LDA,N).

  • on entry, it's the N-by-N matrix A. iconic, she's herself πŸ’…
  • on exit, A has been overwritten by its Schur form T. girl got a whole glow-up, she does not come back the same 😭

LDA ✨

LDA is INTEGER β€” the leading dimension of the array A, and LDA >= max(1,N). respect the constraint fr fr

SDIM πŸŽ€

SDIM is INTEGER.

  • if SORT = 'N', then SDIM = 0 (she's empty, she's at peace)
  • if SORT = 'S', then SDIM = number of eigenvalues for which SELECT is true β€” i.e. the count of the chosen ones πŸ‘‘

W ⭐

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

W contains the computed eigenvalues, in the same order that they appear on the diagonal of the output Schur form T. order matters, bestie, do not shuffle 🫢

VS πŸ¦‹

VS is a COMPLEX*16 array, dimension (LDVS,N).

  • if JOBVS = 'V', VS contains the unitary matrix Z of Schur vectors πŸ’œ
  • if JOBVS = 'N', VS is not referenced β€” she's not invited to this one

LDVS 🌈

LDVS is INTEGER β€” the leading dimension of the array VS. LDVS >= 1; and if JOBVS = 'V', then LDVS >= N. conditional queen πŸ’…

WORK πŸ”₯

WORK is a COMPLEX*16 array, dimension (MAX(1,LWORK)).

on exit, if INFO = 0, then WORK(1) returns the optimal LWORK. she's snitching on the perfect size, love that for her ✨

LWORK πŸ’€

LWORK is INTEGER β€” the dimension of the array WORK. LWORK >= max(1,2*N).

for good performance, LWORK must generally be larger. lowkey the bigger the better, she's high-maintenance like that πŸ’…

if LWORK = -1, then a workspace query is assumed. the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. so like, she's just window shopping, no purchase, no complaints πŸ™ˆ

RWORK πŸ“

RWORK is a DOUBLE PRECISION array, dimension (N). real ones only, no imaginary energy here ngl

BWORK 🧚

BWORK is a LOGICAL array, dimension (N).

not referenced if SORT = 'N'. she's staying home 🫢

INFO πŸ‘‘

INFO is INTEGER.

  • = 0: successful exit. slay, we ate πŸŽ‰
  • < 0: if INFO = -i, the i-th argument had an illegal value. somebody misbehaved 😭
  • > 0: if INFO = i, and i is:
    • <= N: the QR algorithm failed to compute all the eigenvalues; elements 1:ILO-1 and i+1:N of W contain those eigenvalues which have converged; if JOBVS = 'V', VS contains the matrix which reduces A to its partially converged Schur form. (partially converged is still a vibe, ok, she did her best πŸ’€)
    • = N+1: the eigenvalues could not be reordered because some eigenvalues were too close to separate β€” the problem is very ill-conditioned. this is the "they're too similar to tell apart" situation and it's giving messy 😭
    • = N+2: after reordering, roundoff changed values of some complex eigenvalues so that leading eigenvalues in the Schur form no longer satisfy SELECT = .TRUE.. this could also be caused by underflow due to scaling. so like, either roundoff or underflow ruined the plan. very "it's not you it's the floating point" energy 🫠

Author πŸŽ€

the whole squad that made this happen:

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

Definition at line 195 of file zgees.f.


Author ✨

Generated automatically by Doxygen for LAPACK from the source code. iykyk, the docs wrote themselves (kind of) 🫢


and that's a wrap on this LAPACK page bestie!! πŸ’–βœ¨ LAPACK Version 3.12.0, the gees(3) page β€” go forth and compute, you absolute icon, no cap πŸ‘‘πŸŽ€πŸ¦‹

πŸ“¦ where this page comes from