SRC/dtrsen.f(3)

📦
version 3.12.1 · 7 versions
, in arch rolling

🌸 SRC/dtrsen.f(3) — like, the actual manual page, bestie 🌸

Okay so this is from the Library Functions Manual, and the page itself is SRC/dtrsen.f(3) — yes the filename is literally the vibe, it's a Fortran source file (dtrsen.f) and its section-3 manpage, all in one 💅

✨ NAME ✨

SRC/dtrsen.f — that's it, that's the name, no cap 🎀

✨ SYNOPSIS ✨

🦋 Functions/Subroutines 🦋

  • subroutine dtrsen (job, compq, select, n, t, ldt, q, ldq, wr, wi, m, s, sep, work, lwork, iwork, liwork, info) — the whole entire function signature, copied exactly, don't @ me 🫶

And under it, simply:

DTRSEN

That's the routine's name. Short, iconic, main character energy 👑

💜 So what's the deal with this one 💜

Bestie, look at that argument list. Eighteen arguments. One-eight. job, compq, select, n, t, ldt, q, ldq, wr, wi, m, s, sep, work, lwork, iwork, liwork, info — that's the full roster and not a single one of them is getting cut from the group chat 😭

This is DTRSEN, and it's a Fortran subroutine (lowercase dtrsen, because Fortran has no chill about case in the docs but also all the chill in the compiler, iykyk). It lives in the file SRC/dtrsen.f, which is exactly what the page title says, so at least nobody's out here lying to us 🌈

Heads up bestie — this is part 1 of 3. The rest of the page is coming, don't wander off 💖

🔥 DTRSEN 🔥

That's the routine name, standing on its own like it owns the place.

Honestly? The way this page just drops DTRSEN and nothing else here, like a celebrity walking past the paparazzi without a word 💀 Keep reading though — more parts are on the way, and we're gonna get into all eighteen of those arguments. Periodt 🍓

part 1 done, stay tuned for part 2 ✨

💅 Function/Subroutine Documentation 💅

   subroutine dtrsen (character job, character compq, logical, dimension( * )
       select, integer n, double precision, dimension( ldt, * ) t, integer ldt,
       double precision, dimension( ldq, * ) q, integer ldq, double precision,
       dimension( * ) wr, double precision, dimension( * ) wi, integer m,
       double precision s, double precision sep, double precision, dimension( *
       ) work, integer lwork, integer, dimension( * ) iwork, integer liwork,
       integer info)

👑 DTRSEN 👑

🌸 Purpose 🌸

Okay bestie, so DTRSEN reorders the real Schur factorization of a real matrix A = Q*T*Q**T, so that a selected cluster of eigenvalues shows up in the leading diagonal blocks of the upper quasi-triangular matrix T, and the leading columns of Q form an orthonormal basis of the corresponding right invariant subspace. Iconic, truly.

Optionally — yes, it can do extra credit — the routine computes the reciprocal condition numbers of the cluster of eigenvalues and/or the invariant subspace. Obsessed.

T must be in Schur canonical form (as returned by DHSEQR), that is, block upper triangular with 1-by-1 and 2-by-2 diagonal blocks; each 2-by-2 diagonal block has its diagonal elements equal and its off-diagonal elements of opposite sign. That part is non-negotiable, bestie. 💅

✨ Parameters ✨

  • JOB — JOB is CHARACTER*1. It specifies whether condition numbers are required for the cluster of eigenvalues (S) or the invariant subspace (SEP): = 'N': none; = 'E': for eigenvalues only (S); = 'V': for invariant subspace only (SEP); = 'B': for both eigenvalues and invariant subspace (S and SEP). Slay.
  • COMPQ — COMPQ is CHARACTER*1. = 'V': update the matrix Q of Schur vectors; = 'N': do not update Q. Simple as that. ✨
  • SELECT — SELECT is LOGICAL array, dimension (N). It specifies the eigenvalues in the selected cluster. To select a real eigenvalue w(j), SELECT(j) must be set to .TRUE.. To select a complex conjugate pair of eigenvalues w(j) and w(j+1), corresponding to a 2-by-2 diagonal block, either SELECT(j) or SELECT(j+1) or both must be set to .TRUE.; a complex conjugate pair of eigenvalues must be either both included in the cluster or both excluded. No halfsies, periodt. 🎀
  • N — N is INTEGER. The order of the matrix T. N >= 0. Respect.
  • T — T is DOUBLE PRECISION array, dimension (LDT,N). On entry, the upper quasi-triangular matrix T, in Schur canonical form. On exit, T is overwritten by the reordered matrix T, again in Schur canonical form, with the selected eigenvalues in the leading diagonal blocks. Glow-up complete. 🦋
  • LDT — LDT is INTEGER. The leading dimension of the array T. LDT >= max(1,N). Keep it valid, bestie.
  • Q — Q is DOUBLE PRECISION array, dimension (LDQ,N). On entry, if COMPQ = 'V', the matrix Q of Schur vectors. On exit, if COMPQ = 'V', Q has been postmultiplied by the orthogonal transformation matrix which reorders T; the leading M columns of Q form an orthonormal basis for the specified invariant subspace. If COMPQ = 'N', Q is not referenced. She’s off the invite list in that case. 🙈
  • LDQ — LDQ is INTEGER. The leading dimension of the array Q. LDQ >= 1; and if COMPQ = 'V', LDQ >= N. 💜
  • WR — WR is DOUBLE PRECISION array, dimension (N). Real parts. Yes bestie, the real parts are coming in this array.
  • WI — WI is DOUBLE PRECISION array, dimension (N). The real and imaginary parts, respectively, of the reordered eigenvalues of T. The eigenvalues are stored in the same order as on the diagonal of T, with WR(i) = T(i,i) and, if T(i:i+1,i:i+1) is a 2-by-2 diagonal block, WI(i) > 0 and WI(i+1) = -WI(i). Note that if a complex eigenvalue is sufficiently ill-conditioned, then its value may differ significantly from its value before reordering. So like… keep an eye on her. 😭
  • M — M is INTEGER. The dimension of the specified invariant subspace. 0 < = M <= N. Math said what it said. 🌸
  • S — S is DOUBLE PRECISION. If JOB = 'E' or 'B', S is a lower bound on the reciprocal condition number for the selected cluster of eigenvalues. S cannot underestimate the true reciprocal condition number by more than a factor of sqrt(N). If M = 0 or N, S = 1. If JOB = 'N' or 'V', S is not referenced. She’s on standby. ✨
  • SEP — SEP is DOUBLE PRECISION. If JOB = 'V' or 'B', SEP is the estimated reciprocal condition number of the specified invariant subspace. If M = 0 or N, SEP = norm(T). If JOB = 'N' or 'E', SEP is not referenced. Main character only when requested. 👑
  • WORK — WORK is DOUBLE PRECISION array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. She’s working overtime but making it cute. 🫶
  • LWORK — LWORK is INTEGER. The dimension of the array WORK. If JOB = 'N', LWORK >= max(1,N); if JOB = 'E', LWORK >= max(1,M*(N-M)); if JOB = 'V' or 'B', LWORK >= max(1,2*M*(N-M)). 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. Query mode ate, honestly. 💅
  • IWORK — IWORK is INTEGER array, dimension (MAX(1,LIWORK)). On exit, if INFO = 0, IWORK(1) returns the optimal LIWORK. Integer bestie has entered the chat. 🌈
  • LIWORK — LIWORK is INTEGER. The dimension of the array IWORK. If JOB = 'N' or 'E', LIWORK >= 1; if JOB = 'V' or 'B', LIWORK >= max(1,M*(N-M)). If LIWORK = -1, then a workspace query is assumed; the routine only calculates the optimal size of the IWORK array, returns this value as the first entry of the IWORK array, and no error message related to LIWORK is issued by XERBLA. Same energy, different array. ⭐
  • INFO — INFO is INTEGER. = 0: successful exit; < 0: if INFO = -i, the i-th argument had an illegal value; = 1: reordering of T failed because some eigenvalues are too close to separate (the problem is very ill-conditioned); T may have been partially reordered, and WR and WI contain the eigenvalues in the same order as in T; S and SEP (if requested) are set to zero. When it’s giving = 1, that’s the dramatic plot twist — not a slay. 💀

👑 AUTHOR 👑

okay so here's the tea: nobody actually hand-wrote this page. it's literally Generated automatically by Doxygen for LAPACK from the source code. — so if you were about to go hunt down a human author to thank, bestie, there isn't one to @ 😭 the doc fairy (aka Doxygen) just vibed off the LAPACK source and cranked this out. no cap, that's the whole origin story 💅✨

aaaand that's a wrap on SRC/dtrsen.f(3), bestie 🎀 you made it to the end, which is honestly iconic behavior. this whole glow-up came to you courtesy of LAPACK, Version 3.12.0 — go forth and slay, you absolute main character 💖🦋🌸

📦 where this page comes from