PDLAHQR(l)

📦 version 1.5, in ubuntu jammy

💖 PDLAHQR(l) — LAPACK auxiliary routine (version 1.5) 💖

okay bestie, welcome to PDLAHQR(l) — a LAPACK auxiliary routine, version 1.5. This is part 1, and it's giving Hessenberg energy 💅.

✨ NAME ✨

PDLAHQR — an auxiliary routine used to find the Schur decomposition and or eigenvalues of a matrix already in Hessenberg form from cols ILO to IHI. 🦋

✨ SYNOPSIS ✨

Here's the whole signature, no cap:

       SUBROUTINE PDLAHQR( WANTT, WANTZ, N, ILO, IHI, A, DESCA, WR, WI, ILOZ,
                           IHIZ, Z, DESCZ, WORK, LWORK, IWORK, ILWORK, INFO )

           LOGICAL         WANTT, WANTZ

           INTEGER         IHI, IHIZ, ILO, ILOZ, ILWORK, INFO, LWORK, N, ROTN

           INTEGER         DESCA( * ), DESCZ( * ), IWORK( * )

           DOUBLE          PRECISION A( * ), WI( * ), WORK( * ), WR( * ), Z( *
                           )

✨ PURPOSE ✨

PDLAHQR is an auxiliary routine used to find the Schur decomposition and or eigenvalues of a matrix already in Hessenberg form from cols ILO to IHI. That's the whole vibe. 💖

🧠 Notes 🧠

Each global data object is described by an associated description vector. This vector stores the information required to establish the mapping between an object element and its corresponding process and memory location.

Let A be a generic term for any 2D block cyclicly distributed array. Such a global array has an associated description vector DESCA. In the following comments, the character _ should be read as "of the global array".

📋 NOTATION / STORED IN / EXPLANATION 📋

DTYPE_A(global) — stored in DESCA( DTYPE_ ) — The descriptor type. In this case, DTYPE_A = 1.
CTXT_A (global) — stored in DESCA( CTXT_ ) — The BLACS context handle, indicating the BLACS process grid A is distributed over. The context itself is global, but the handle (the integer value) may vary.
M_A (global) — stored in DESCA( M_ ) — The number of rows in the global array A.
N_A (global) — stored in DESCA( N_ ) — The number of columns in the global array A.
MB_A (global) — stored in DESCA( MB_ ) — The blocking factor used to distribute the rows of the array.
NB_A (global) — stored in DESCA( NB_ ) — The blocking factor used to distribute the columns of the array.
RSRC_A (global) — stored in DESCA( RSRC_ ) — The process row over which the first row of the array A is distributed.
CSRC_A (global) — stored in DESCA( CSRC_ ) — The process column over which the first column of the array A is distributed.
LLD_A (local) — stored in DESCA( LLD_ ) — The leading dimension of the local array. LLD_A >= MAX(1,LOCr(M_A)).

Let K be the number of rows or columns of a distributed matrix, and assume that its process grid has dimension p x q.

LOCr( K ) denotes the number of elements of K that a process would receive if K were distributed over the p processes of its process column.

Similarly, LOCc( K ) denotes the number of elements of K that a process would receive if K were distributed over the q processes of its process row.

The values of LOCr() and LOCc() may be determined via a call to the ScaLAPACK tool function, NUMROC:

               LOCr( M ) = NUMROC( M, MB_A, MYROW, RSRC_A, NPROW ),
               LOCc( N ) = NUMROC( N, NB_A, MYCOL, CSRC_A, NPCOL ).  An upper
       bound for these quantities may be computed by:
               LOCr( M ) <= ceil( ceil(M/MB_A)/NPROW )*MB_A
               LOCc( N ) <= ceil( ceil(N/NB_A)/NPCOL )*NB_A

✨ ARGUMENTS ✨

WANTT (global input) LOGICAL — set it to .TRUE. and you're asking for the full Schur form T 💖. Set it to .FALSE. and bestie, we're only here for the eigenvalues, nothing more.
WANTZ (global input) LOGICAL — .TRUE. means you want the matrix of Schur vectors Z 🦋. .FALSE. means no Schur vectors for you, sorry bestie.
N (global input) INTEGER — the order of the Hessenberg matrix A (and of Z too, if WANTZ is on). Constraint: N >= 0. no cap 📏
ILO (global input) INTEGER and IHI (global input) INTEGER — so here's the deal: it's assumed that A is already upper quasi-triangular in rows and columns IHI+1:N, and that A(ILO,ILO-1) = 0 (unless ILO = 1, obviously 💅). PDLAHQR works primarily with the Hessenberg submatrix in rows and columns ILO to IHI, but it applies transformations to all of H if WANTT is .TRUE.. Constraints: 1 <= ILO <= max(1,IHI) and IHI <= N.
A (global input/output) DOUBLE PRECISION array, dimension (DESCA(LLD_),*) — on entry, this is your upper Hessenberg matrix A 👑. On exit, if WANTT is .TRUE., A is upper quasi-triangular in rows and columns ILO:IHI, with any 2-by-2 (or bigger!) diagonal blocks not yet in standard form (yeah, we know, it's giving chaos 🫠). If WANTT is .FALSE., the contents of A are unspecified on exit — like, genuinely unspecified, don't come for us.
DESCA (global and local input) INTEGER array of dimension DLEN_ — the array descriptor for the distributed matrix A 🎀.
WR (global replicated output) DOUBLE PRECISION array, dimension (N) and WI (global replicated output) DOUBLE PRECISION array, dimension (N) — these two hold the real and imaginary parts of the computed eigenvalues ILO to IHI, stored in the corresponding elements of WR and WI. If two eigenvalues come out as a complex conjugate pair, they get stored in consecutive elements of WR and WI, say the i-th and (i+1)th, with WI(i) > 0 and WI(i+1) < 0. And if WANTT is .TRUE., the eigenvalues are stored in the same order as on the diagonal of the Schur form returned in A. Heads up though: A may be returned with larger diagonal blocks until the next release 😭.
ILOZ (global input) INTEGER and IHIZ (global input) INTEGER — these specify the rows of Z that transformations must be applied to, but only if WANTZ is .TRUE.. Constraints: 1 <= ILOZ <= ILO and IHI <= IHIZ <= N ✨.
Z (global input/output) DOUBLE PRECISION array — if WANTZ is .TRUE., then on entry Z must contain the current matrix Z of transformations accumulated by PDHSEQR, and on exit Z has been updated; transformations get applied only to the submatrix Z(ILOZ:IHIZ,ILO:IHI). If WANTZ is .FALSE., Z is not referenced at all, like it doesn't even exist 💀.
DESCZ (global and local input) INTEGER array of dimension DLEN_ — the array descriptor for the distributed matrix Z 🌸.
WORK (local output) DOUBLE PRECISION array of size LWORK — (unless LWORK=-1, in which case WORK must be at least size 1).
LWORK (local input) INTEGER — WORK(LWORK) is a local array, and LWORK is assumed big enough so that:

LWORK >= 3*N + MAX( 2*MAX(DESCZ(LLD_),DESCA(LLD_)) + 2*LOCc(N),
                    7*Ceil(N/HBL)/LCM(NPROW,NPCOL)) + MAX( 2*N,
                    (8*LCM(NPROW,NPCOL)+2)**2 )

If LWORK=-1, then WORK(1) gets set to the above number and the code returns immediately 🏃‍♀️.

IWORK (global and local input) INTEGER array of size ILWORK — this will hold some of the IBLK integer arrays. It's held as a place holder for a future release. Currently unreferenced 🙈.
ILWORK (local input) INTEGER — this will hold the size of the IWORK array. Also a place holder for a future release. Also currently unreferenced 🙈.
INFO (global output) INTEGER — the vibe check on how everything went:
- < 0: parameter number -INFO is incorrect or inconsistent ❌
- = 0: successful exit 🎉
- > 0: PDLAHQR failed to compute all the eigenvalues ILO to IHI in a total of 30*(IHI-ILO+1) iterations; if INFO = i, elements i+1:ihi of WR and WI contain those eigenvalues which have been successfully computed (partial slay, honestly).

🧠 Logic 🧠

This algorithm is very similar to _LAHQR. But unlike _LAHQR, instead of sending one double shift through the largest unreduced submatrix, this algorithm sends multiple double shifts and spaces them apart so that there can be parallelism across several processor row/columns 🔥. Another critical difference: this algorithm aggregates multiple transforms together in order to apply them in a block fashion. it's giving efficiency, periodt.

🔍 Important Local Variables 🔍

IBLK = the maximum number of bulges that can be computed. Currently fixed. In future releases this won't be fixed.
HBL = the square block size (HBL=DESCA(MB_)=DESCA(NB_)).
ROTN = the number of transforms to block together.
NBULGE = the number of bulges that will be attempted on the current submatrix.
IBULGE = the current number of bulges started.
K1(*),K2(*) = the current bulge loops from K1(*) to K2(*).

📞 Subroutines 📞

From LAPACK, this routine calls:

DLAHQR -> Serial QR used to determine shifts and eigenvalues.
DLARFG -> Determine the Householder transforms.

From ScaLAPACK, this routine calls:

PDLACONSB -> To determine where to start each iteration.
DLAMSH -> Sends multiple shifts through a small submatrix to see how the consecutive subdiagonals change (if PDLACONSB indicates we can start a run in the middle).
PDLAWIL -> Given the shift, get the transformation.
DLASORTE -> Pair up eigenvalues so that reals are paired.
PDLACP3 -> Parallel array to local replicated array copy & back.
DLAREF -> Row/column reflector applier. Core routine here 👑.
PDLASMSUB -> Finds negligible subdiagonal elements.

🚨 Current Notes and/or Restrictions 🚨

This code requires the distributed block size to be square and at least six (6); unlike simpler codes like LU, this algorithm is extremely sensitive to block size. Unwise choices of too small a block size can lead to bad performance 😭.
This code requires A and Z to be distributed identically and have identical contxts. A future version may allow Z to have a different contxt to 1D row map it to all nodes (so no communication on Z is necessary).
This release currently does not have a routine for resolving the Schur blocks into regular 2x2 form after this code is completed. Because of this, a significant performance impact is required while the deflation is done by sometimes a single column of processors 🫠.
This code does not currently block the initial transforms so that none of the rows or columns for any bulge are completed until all are started. To offset pipeline start-up it is recommended that at least 2*LCM(NPROW,NPCOL) bulges are used (if possible).
The maximum number of bulges currently supported is fixed at 32. In future versions this will be limited only by the incoming WORK and IWORK array.
The matrix A must be in upper Hessenberg form. If elements below the subdiagonal are nonzero, the resulting transforms may be nonsimilar. This is also true with the LAPACK routine DLAHQR 💀.
For this release, this code has only been tested for RSRC_=CSRC_=0, but it has been written for the general case.
Currently, all the eigenvalues are distributed to all the nodes. Future releases will probably distribute the eigenvalues by the column partitioning.
The internals of this routine are subject to change 🔄.
To optimize this for your architecture, try tuning DLAREF ✨.
This code has only been tested for WANTZ = .TRUE. and may behave unpredictably for WANTZ set to .FALSE. 🙈.

💖 Implemented by 💖

G. Henry, May 1, 1997

and that's the whole page bestie!! 🎀 this one's from LAPACK version 1.5, dated 12 May 1997 — vintage icon behavior, honestly 👑✨

📦 where this page comes from

ubuntu jammy: scalapack-doc 1.5-11
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms