SRC/zhetrd.f(3)

📦
version 3.12.1 · 4 versions
, in arch rolling

✨ SRC/zhetrd.f ✨

okay so bestie, welcome to the glow-up era of zhetrd — no cap, this is the routine that takes your complex Hermitian matrix and literally serves it as a real symmetric tridiagonal. iconic behavior only 💅

🎀 SYNOPSIS 🎀

Functions/Subroutines

  • subroutine zhetrd (uplo, n, a, lda, d, e, tau, work, lwork, info) — the one, the only, ZHETRD 👑

💖 Function/Subroutine Documentation 💖

subroutine zhetrd (character uplo, integer n, complex*16, dimension( lda, * ) a, integer lda, double precision, dimension( * ) d, double precision, dimension( * ) e, complex*16, dimension( * ) tau, complex*16, dimension( * ) work, integer lwork, integer info)

ZHETRD — say it with me, this is the moment 🫶

🌸 Purpose 🌸

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

so basically: your fancy Hermitian matrix goes in, a real symmetric tridiagonal one comes out, and the transformation is a whole unitary similarity situation. it's giving main character energy, fr fr ✨

🌈 Parameters 🌈

UPLO

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

pick your fighter: 'U' for upper, 'L' for lower. that's the whole vibe check 😌

N

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

the order, bestie. and it's gotta be N >= 0 — no negative nonsense here 🙈

A

A is COMPLEX*16 array, dimension (LDA,N) On entry, the Hermitian matrix A. If UPLO = 'U', the leading N-by-N upper triangular part of A contains the upper triangular part of the matrix A, and the strictly lower triangular part of A is not referenced. If UPLO = 'L', the leading N-by-N lower triangular part of A contains the lower triangular part of the matrix A, and the strictly upper triangular part of A is not referenced. 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.

okay so on entry it's your Hermitian queen A. if UPLO = 'U', the leading N-by-N upper triangular part holds the upper triangle, and the strictly lower triangular part is not referenced — we don't even look at it, she's off duty 💀. if UPLO = 'L', it's the mirror image: leading N-by-N lower triangular part holds the lower triangle, strictly upper triangular part not referenced.

on exit it's a whole different story, so pay attention 🔥:

  • UPLO = 'U' → the diagonal and first superdiagonal of A get overwritten with the corresponding elements of the tridiagonal matrix T, and the elements above the first superdiagonal, together with the array TAU, represent the unitary matrix Q as a product of elementary reflectors.
  • UPLO = 'L' → the diagonal and first subdiagonal of A get over-written by the corresponding elements of T, and the elements below the first subdiagonal, together with TAU, represent Q as a product of elementary reflectors.

see Further Details for the tea 🍓

LDA

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

the leading dimension, babe. LDA >= max(1,N) — respect the constraint or catch these errors 😤

D

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

the diagonal girlies of T, and yes: D(i) = A(i,i). literally just vibes on the diagonal 💜

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, N-1 of them. E(i) = A(i,i+1) if UPLO = 'U', and E(i) = A(i+1,i) if UPLO = 'L' — direction matters, iykyk 🌸

TAU

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

the scalar factors of the elementary reflectors — N-1 of them. further details below, don't worry 🎀

WORK

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

the workspace, dimension MAX(1,LWORK). on exit, if INFO = 0, then WORK(1) returns the optimal LWORK — she's helpful like that ✨

LWORK

LWORK is INTEGER The dimension of the array WORK. LWORK >= 1. For optimum performance LWORK >= N*NB, where NB is the optimal blocksize. 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 dimension of WORK, and LWORK >= 1. for optimum performance (read: maximum slay 🔥) you want LWORK >= N*NB, where NB is the optimal blocksize.

and hey — if LWORK = -1, that's a workspace query! the routine only calculates the optimal size of the WORK array, returns that value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. so no, you're not in trouble, it's a whole different mode 💅

INFO

INFO is INTEGER = 0: successful exit < 0: if INFO = -i, the i-th argument had an illegal value
  • = 0: successful exit, we ate and left no crumbs 👑
  • < 0: if INFO = -i, the i-th argument had an illegal value 😭

🦋 Author 🦋

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

the collective legends behind all this, periodt 🫶

🧚 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 A(1:i-1,i+1), and tau in TAU(i).

so when UPLO = 'U', Q is a product of elementary reflectors in that order:

Q = H(n-1) . . . H(2) H(1).

and each H(i) looks like:

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. on exit, v(1:i-1) is stored in A(1:i-1,i+1), and tau lives in TAU(i). bookkeeping icon behavior 📚✨

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 A(i+2:n,i), and tau in TAU(i).

flip it to UPLO = 'L' and the order reverses:

Q = H(1) H(2) . . . H(n-1).

each H(i) is again:

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

where tau is a complex scalar, v is a complex vector with v(1:i) = 0 and v(i+1) = 1. on exit, v(i+2:n) is stored in A(i+2:n,i), and tau in TAU(i). same energy, opposite direction 🔄

The contents of A on exit are illustrated by the following examples with n = 5: if UPLO = 'U': if UPLO = 'L': text ( d e v2 v3 v4 ) ( d ) ( d e v3 v4 ) ( e d ) ( d e v4 ) ( v1 e d ) ( d e ) ( v1 v2 e d ) ( d ) ( v1 v2 v3 e d )

here's what A looks like on exit, n = 5, side by side:

if UPLO = 'U':                       if UPLO = 'L':

  (  d   e   v2  v3  v4 )              (  d                  )
  (      d   e   v3  v4 )              (  e   d              )
  (          d   e   v4 )              (  v1  e   d          )
  (              d   e  )              (  v1  v2  e   d      )
  (                  d  )              (  v1  v2  v3  e   d  )
where d and e denote diagonal and off-diagonal elements of T, and vi denotes an element of the vector defining H(i).

quick legend so nobody's confused 😌: d and e are the diagonal and off-diagonal elements of T, and vi is an element of the vector defining H(i). that's the whole map, bestie 🗺️💖

⭐ Definition ⭐

Definition at line 191 of file zhetrd.f.

💜 Author 💜

Generated automatically by Doxygen for LAPACK from the source code.

aaaand that's the page! this masterpiece was auto-generated by Doxygen for LAPACK, Version 3.12.0, dated on the SRC/zhetrd.f(3) page — catch you in the next manpage, bestie 😭💅🦋

📦 where this page comes from