ZHPTRD(3)

💅 ZHPTRD(3) — bestie's guide to the complex Hermitian packed → tridiagonal glow-up

okay so this is a page from the LAPACK Library Functions Manual and honestly? it's giving linear algebra main character energy. sit down, grab a boba, we're reducing a complex Hermitian matrix to real symmetric tridiagonal form. no cap. 🫶

---

✨ NAME ✨

/home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/SRC/zhptrd.f

that's the whole name, bestie — it's a .f file living its best life in the LAPACK source tree. yes the NAME section is literally just a file path and honestly? iconic. 🎀

---

🌸 SYNOPSIS 🌸

Functions/Subroutines

subroutine ZHPTRD (uplo, n, ap, d, e, tau, info)

ZHPTRD — that's her. that's the girl.

---

🦋 Function/Subroutine Documentation 🦋

subroutine ZHPTRD (character uplo, integer n, complex*16, dimension( * ) ap,
    double precision, dimension( * ) d, double precision, dimension( * ) e,
    complex*16, dimension( * ) tau, integer info)

ZHPTRD 💜 (the full-signature version, for when you need the whole fit)

🎯 Purpose:

ZHPTRD reduces a complex Hermitian matrix A stored in packed form to real symmetric tridiagonal form T by a unitary similarity transformation: Q**H * A * Q = T.

so basically: A comes in complex + Hermitian + packed (squeezed, no zeros), and T comes out real + symmetric + tridiagonal (just the diagonal and its two adjacent lanes). the transformation is Q**H * A * Q = T, and Q is unitary. she did that. 🔥

---

👑 Parameters

UPLO

• UPLO is CHARACTER*1
• = 'U': Upper triangle of A is stored;
• = 'L': Lower triangle of A is stored.

pick your fighter: upper or lower triangle. there is no third option, don't try it. 🙈

N

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

the size of the situation. and yes, N >= 0 — zero is a valid vibe check. ✨

AP

• AP is COMPLEX*16 array, dimension (N*(N+1)/2)
• On entry, the upper or lower triangle of the Hermitian matrix A, packed columnwise in a linear array. The j-th column of A is stored in the array AP as follows:
  • if UPLO = 'U', AP(i + (j-1)*j/2) = A(i,j) for 1<=i<=j;
  • if UPLO = 'L', AP(i + (j-1)*(2*n-j)/2) = A(i,j) for j<=i<=n.
• On exit, if UPLO = 'U', the diagonal and first superdiagonal of A are overwritten by the corresponding elements of the tridiagonal matrix T, and the elements above the first superdiagonal, with the array TAU, represent the unitary matrix Q as a product of elementary reflectors; if UPLO = 'L', the diagonal and first subdiagonal of A are over-written by the corresponding elements of the tridiagonal matrix T, 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.

this is the big one, the packed storage container, the whole personality. 💅 heads up: on exit she gets overwritten. like, gone. the diagonal + first superdiagonal (or subdiagonal) become T's elements, and the rest plus TAU become Q. so if you needed the original A, too late bestie 😭 See Further Details below, i'm not retyping it, it's right there.

D

• D is DOUBLE PRECISION array, dimension (N)
• The diagonal elements of the tridiagonal matrix T: D(i) = A(i,i).

the main diagonal of T, cute and real and double precision. ⭐

E

• E is DOUBLE PRECISION array, dimension (N-1)
• The off-diagonal elements of the tridiagonal matrix T: E(i) = A(i,i+1) if UPLO = 'U', E(i) = A(i+1,i) if UPLO = 'L'.

the off-diagonal besties — note the size is N-1, because a tridiagonal's off-diagonals are one shorter than the diagonal. math said balance. 🧚

TAU

• TAU is COMPLEX*16 array, dimension (N-1)
• The scalar factors of the elementary reflectors (see Further Details).

the scalars that make the reflectors reflect. also N-1. see Further Details, again, for the actual math. 💜

INFO

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

the vibe check report. 0 means slay, negative means somebody passed a bad argument and we're telling you exactly which one by index. ⚠️

---

🎀 Author

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

the group project that actually got finished. respect. 👑

---

🌈 Further Details:

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

so the 'U' order is backwards (H(n-1) . . . H(2) H(1)) and the 'L' order is forwards (H(1) H(2) . . . H(n-1)) — do NOT mix those up, that's the whole tea. each H(i) is I - tau * v * v**H with those exact zero-and-one patterns on v, and the nonzero part of v gets parked in AP on exit while tau goes to TAU(i). note: that's overwriting A(1:i-1,i+1) for 'U' and A(i+2:n,i) for 'L' — your original numbers are not coming back. 😭

Definition at line 150 of file zhptrd.f.

---

okay that's the whole page, you're officially a ZHPTRD understander 💖

---

✨ cute sign-off ✨ this glamorous little document was Generated automatically by Doxygen for LAPACK from the source code, and it's serving LAPACK Version 3.12.0 realness. mwah. 💋🦋🌸