SRC/zgehrd.f(3)

💖 SRC/zgehrd.f 💖

okay so bestie, welcome to the Library Functions Manual entry for SRC/zgehrd.f — yes the whole page is literally named after one file, iconic behavior honestly. this is a LAPACK girlie and she's about to reduce your complex general matrix to upper Hessenberg form and she is going to slay while doing it. no cap. 🦋

---

✨ SYNOPSIS ✨

🎀 Functions/Subroutines 🎀

• subroutine zgehrd (n, ilo, ihi, a, lda, tau, work, lwork, info) — bestie this is the ZGEHRD. that's the whole vibe.

---

🔥 Function/Subroutine Documentation 🔥

💅 the actual subroutine, fr fr

subroutine zgehrd (integer n, integer ilo, integer ihi, complex*16,
    dimension( lda, * ) a, integer lda, complex*16, dimension( * ) tau,
    complex*16, dimension( * ) work, integer lwork, integer info)

ZGEHRD 👑

🌸 Purpose 🌸

ZGEHRD reduces a complex general matrix A to upper Hessenberg form H by an unitary similarity transformation: Q**H * A * Q = H .

that's it. that's the whole mission statement. she takes your messy general matrix and gives you the glow-up. ✨

💜 Parameters 💜

N

N is INTEGER The order of the matrix A. N >= 0.

so like, how big the matrix is. N >= 0, and zero is genuinely allowed, she's not picky. 🫶

ILO

ILO is INTEGER

just an integer bestie, that's all it says here 😭 (the lore drops in IHI and in Further Details, keep reading)

IHI

IHI is INTEGER It is assumed that A is already upper triangular in rows and columns 1:ILO-1 and IHI+1:N. ILO and IHI are normally set by a previous call to ZGEBAL; otherwise they should be set to 1 and N respectively. See Further Details. 1 <= ILO <= IHI <= N, if N > 0; ILO=1 and IHI=0, if N=0.

okay so this is the part where you gotta respect the boundaries: A is already upper triangular in rows and columns 1:ILO-1 and IHI+1:N. those zones are off-limits, do not touch. ILO and IHI usually come from a previous call to ZGEBAL — if you don't have those, just set them to 1 and N. and the rules: 1 <= ILO <= IHI <= N if N > 0; and if N=0 then ILO=1 and IHI=0. iykyk. 💀

A

A is COMPLEX*16 array, dimension (LDA,N) On entry, the N-by-N general matrix to be reduced. On exit, the upper triangle and the first subdiagonal of A are overwritten with the upper Hessenberg matrix H, and the elements below the first subdiagonal, with the array TAU, represent the unitary matrix Q as a product of elementary reflectors. See Further Details.

so A is a COMPLEX*16 array of dimension (LDA,N). on entry: the N-by-N general matrix, ready for her makeover. on exit: the upper triangle and the first subdiagonal get overwritten with the upper Hessenberg matrix H, and everything below the first subdiagonal — together with the array TAU — represents the unitary matrix Q as a product of elementary reflectors. she does overwrite your input, that's the deal, that's the arrangement. 🙈

LDA

LDA is INTEGER The leading dimension of the array A. LDA >= max(1,N).

the leading dimension of A. LDA >= max(1,N). that's it, that's the requirement, respect it. 💅

TAU

TAU is COMPLEX*16 array, dimension (N-1) The scalar factors of the elementary reflectors (see Further Details). Elements 1:ILO-1 and IHI:N-1 of TAU are set to zero.

TAU is a COMPLEX*16 array, dimension (N-1), holding the scalar factors of the elementary reflectors (Further Details has the receipts). heads up: elements 1:ILO-1 and IHI:N-1 of TAU are set to zero. not your problem, she handles it. 🍓

WORK

WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.

WORK is a COMPLEX*16 array of dimension (MAX(1,LWORK)). on exit, if INFO = 0, then WORK(1) hands you back the optimal LWORK. it's giving "here's what you could have had." ✨

LWORK

LWORK is INTEGER The length of the array WORK. LWORK >= max(1,N). For good performance, LWORK should 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.

the length of the array WORK. hard requirement: LWORK >= max(1,N). but ngl, for good performance LWORK should generally be larger — more room, more speed, the vibe check passes. 🏃‍♀️

also this cute little trick: if LWORK = -1, then a workspace query is assumed. the routine only calculates the optimal size of the WORK array, returns that value as the first entry of the WORK array, and — important — no error message related to LWORK is issued by XERBLA. so you can ask her "how much room do you need" without getting yelled at. queen. 👑

INFO

INFO is INTEGER = 0: successful exit < 0: if INFO = -i, the i-th argument had an illegal value.

• = 0: successful exit 🎉 we ate
• < 0: if INFO = -i, the i-th argument had an illegal value 💀 somebody fed her a bad argument and she's telling you exactly which one

👑 Author 👑

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

four institutions in the credits, absolute main character energy, they all showed up for her. 🌈

🧚 Further Details 🧚

The matrix Q is represented as a product of (ihi-ilo) elementary reflectors Q = H(ilo) H(ilo+1) . . . H(ihi-1). Each H(i) has the form H(i) = I - tau * v * v**H where tau is a complex scalar, and v is a complex vector with v(1:i) = 0, v(i+1) = 1 and v(ihi+1:n) = 0; v(i+2:ihi) is stored on exit in A(i+2:ihi,i), and tau in TAU(i).

so the matrix Q is a product of (ihi-ilo) elementary reflectors:

Q = H(ilo) H(ilo+1) . . . H(ihi-1).

and each H(i) has the form:

H(i) = I - tau * v * v**H

where tau is a complex scalar and v is a complex vector with v(1:i) = 0, v(i+1) = 1 and v(ihi+1:n) = 0. on exit, v(i+2:ihi) lives in A(i+2:ihi,i) and tau lives in TAU(i). everything has a home, nothing is lost. 🫶

The contents of A are illustrated by the following example, with n = 7, ilo = 2 and ihi = 6:

okay bestie, this diagram is genuinely so satisfying, look at the glow-up:

on entry,                        on exit,

( a   a   a   a   a   a   a )    (  a   a   h   h   h   h   a )
(     a   a   a   a   a   a )    (      a   h   h   h   h   a )
(     a   a   a   a   a   a )    (      h   h   h   h   h   h )
(     a   a   a   a   a   a )    (      v2  h   h   h   h   h )
(     a   a   a   a   a   a )    (      v2  v3  h   h   h   h )
(     a   a   a   a   a   a )    (      v2  v3  v4  h   h   h )
(                         a )    (                          a )

where a denotes an element of the original matrix A, h denotes a modified element of the upper Hessenberg matrix H, and vi denotes an element of the vector defining H(i).

so quick legend: a = an element of the original matrix A (untouched, still her), h = a modified element of the upper Hessenberg matrix H (the new her), and vi = an element of the vector defining H(i). the way the as just stay in the corners… that's the boundary thing from IHI, we love consistency. 😭💖

This file is a slight modification of LAPACK-3.0's ZGEHRD subroutine incorporating improvements proposed by Quintana-Orti and Van de Geijn (2006). (See ZLAHR2.)

and the lore 🫶: this file is a slight modification of LAPACK-3.0's ZGEHRD subroutine, incorporating improvements proposed by Quintana-Orti and Van de Geijn (2006). (See ZLAHR2.) we stan a documented upgrade path. 👑

---

Definition at line 166 of file zgehrd.f.

⭐ Author ⭐

Generated automatically by Doxygen for LAPACK from the source code.

---

and that's the whole page bestie!! 🎀 LAPACK, Version 3.12.0, straight from the source of SRC/zgehrd.f(3) — mwah, go reduce something 💋✨