hetrd(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

💖 hetrd(3) — {he,sy}trd: reduction to tridiagonal 💖

okay bestie, welcome to hetrd(3) from the Library Functions Manual — this is the page, the one about squishing your matrix down to tridiagonal form. main character energy fr. there's a whole squad of subroutines here (CHETRD, DSYTRD, SSYTRD, ZHETRD) and they all do the same iconic thing in different flavours. let's get into it ✨

🌸 NAME 🌸

hetrd — {he,sy}trd: reduction to tridiagonal. that's the whole vibe. 💅

✨ SYNOPSIS ✨

🦋 Functions 🦋

subroutine chetrd (uplo, n, a, lda, d, e, tau, work, lwork, info)
    CHETRD
subroutine dsytrd (uplo, n, a, lda, d, e, tau, work, lwork, info)
    DSYTRD
subroutine ssytrd (uplo, n, a, lda, d, e, tau, work, lwork, info)
    SSYTRD
subroutine zhetrd (uplo, n, a, lda, d, e, tau, work, lwork, info)
    ZHETRD

🎀 Detailed Description 🎀

(this is the bit that says everything else lives under Function Documentation — which, yes, is literally the next section. no notes. 🫶)

👑 Function Documentation 👑

🌈 subroutine chetrd 🌈

subroutine chetrd (character uplo, integer n, complex, dimension( lda, * )
    a, integer lda, real, dimension( * ) d, real, dimension( * ) e, complex,
    dimension( * ) tau, complex, dimension( * ) work, integer lwork, integer
    info)

CHETRD — say hi to the complex Hermitian one 💜

💫 Purpose 💫

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

🍓 Parameters 🍓

  • UPLO
UPLO is CHARACTER*1 = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored.
  • N
N is INTEGER The order of the matrix A. N >= 0.
  • A
A is COMPLEX 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.
  • LDA
LDA is INTEGER The leading dimension of the array A. LDA >= max(1,N).
  • D
D is REAL array, dimension (N) The diagonal elements of the tridiagonal matrix T: D(i) = A(i,i).
  • E
E is REAL 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'.
  • TAU
TAU is COMPLEX array, dimension (N-1) The scalar factors of the elementary reflectors (see Further Details).
  • WORK
WORK is COMPLEX array, dimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  • 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.
  • INFO
INFO is INTEGER = 0: successful exit < 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.

🧚 Further Details: 🧚

If UPLO = 'U', the matrix Q is represented as a product of elementary reflectors Q = H(n-1) . . . H(2) H(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(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). If UPLO = 'L', the matrix Q is represented as a product of elementary reflectors Q = H(1) H(2) . . . H(n-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 and v(i+1) = 1; v(i+2:n) is stored on exit in A(i+2:n,i), and tau in TAU(i). The contents of A on exit are illustrated by the following examples with n = 5: if UPLO = 'U': ( d e v2 v3 v4 ) ( d e v3 v4 ) ( d e v4 ) ( d e ) ( d ) if UPLO = 'L': ( d ) ( e d ) ( v1 e d ) ( v1 v2 e 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).

Definition at line 191 of file chetrd.f. 📍

🦋 subroutine dsytrd 🦋

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

DSYTRD — the real symmetric double-precision one, aka the classic 💙

💫 Purpose 💫

DSYTRD reduces a real symmetric matrix A to real symmetric tridiagonal form T by an orthogonal similarity transformation: Q**T * A * Q = T.

🍓 Parameters 🍓

  • UPLO
UPLO is CHARACTER*1 = 'U': Upper triangle of A is stored; = 'L': Lower triangle of A is stored.
  • N
N is INTEGER The order of the matrix A. N >= 0.
  • A
A is DOUBLE PRECISION array, dimension (LDA,N) On entry, the symmetric 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 orthogonal 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 orthogonal matrix Q as a product of elementary reflectors. See Further Details.
  • LDA
LDA is INTEGER The leading dimension of the array A. LDA >= max(1,N).
  • D
D is DOUBLE PRECISION array, dimension (N) The diagonal elements of the tridiagonal matrix T: D(i) = A(i,i).
  • 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'.
  • TAU
TAU is DOUBLE PRECISION array, dimension (N-1) The scalar factors of the elementary reflectors (see Further Details).
  • WORK
WORK is DOUBLE PRECISION array, dimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  • 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.
  • INFO
INFO is INTEGER = 0: successful exit < 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.

🧚 Further Details: 🧚

and this is the part where the page keeps rolling, bestie — hold that thought 💜

If UPLO = 'U', the matrix Q is represented as a product of elementary reflectors — like a little chain of transformations doing their thing, bestie 💅:

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

Each H(i) has the form:

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

where tau is a real scalar, and v is a real 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). 🫶

If UPLO = 'L', the matrix Q is represented as a product of elementary reflectors:

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

Each H(i) has the form:

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

where tau is a real scalar, and v is a real 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). ✨

The contents of A on exit are illustrated by the following examples with n = 5:

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). 🦋

Definition at line 191 of file dsytrd.f.

🌸 ssytrd — SSYTRD 🌸

   subroutine ssytrd (character uplo, integer n, real, dimension( lda, * ) a,
       integer lda, real, dimension( * ) d, real, dimension( * ) e, real,
       dimension( * ) tau, real, dimension( * ) work, integer lwork, integer
       info)

Purpose ✨

SSYTRD reduces a real symmetric matrix A to real symmetric tridiagonal form T by an orthogonal similarity transformation: Q**T * A * Q = T. Periodt. 💖

Parameters 🎀

  • UPLO — UPLO is CHARACTER*1
    • = 'U': Upper triangle of A is stored;
    • = 'L': Lower triangle of A is stored.
  • N — N is INTEGER The order of the matrix A. N >= 0.
  • A — A is REAL array, dimension (LDA,N) On entry, the symmetric 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 orthogonal matrix Q as a product of elementary reflectors; if UPLO = 'L', the diagonal and first subdiagonal of A are overwritten by the corresponding elements of the tridiagonal matrix T, and the elements below the first subdiagonal, with the array TAU, represent the orthogonal matrix Q as a product of elementary reflectors. See Further Details.
  • LDA — LDA is INTEGER The leading dimension of the array A. LDA >= max(1,N).
  • D — D is REAL array, dimension (N) The diagonal elements of the tridiagonal matrix T: D(i) = A(i,i).
  • E — E is REAL 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'.
  • TAU — TAU is REAL array, dimension (N-1) The scalar factors of the elementary reflectors (see Further Details).
  • WORK — WORK is REAL array, dimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  • 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.
  • INFO — INFO is INTEGER
    • = 0: successful exit
    • < 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.

Further Details 🔥

If UPLO = 'U', the matrix Q is represented as a product of elementary reflectors:

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

Each H(i) has the form:

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

where tau is a real scalar, and v is a real 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). 💜

If UPLO = 'L', the matrix Q is represented as a product of elementary reflectors:

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

Each H(i) has the form:

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

where tau is a real scalar, and v is a real 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). 🌈

The contents of A on exit are illustrated by the following examples with n = 5:

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). 🎀

Definition at line 191 of file ssytrd.f.

🦋 zhetrd — ZHETRD 🦋

   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)

Purpose ✨

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

Parameters 🎀

  • UPLO — UPLO is CHARACTER*1
    • = 'U': Upper triangle of A is stored;
    • = 'L': Lower triangle of A is stored.
  • N — N is INTEGER The order of the matrix A. N >= 0.
  • 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 overwritten 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.
  • LDA — LDA is INTEGER The leading dimension of the array A. LDA >= max(1,N).
  • D — D is DOUBLE PRECISION array, dimension (N) The diagonal elements of the tridiagonal matrix T: D(i) = A(i,i).
  • 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'.
  • TAU — TAU is COMPLEX*16 array, dimension (N-1) The scalar factors of the elementary reflectors (see Further Details).
  • WORK — WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)) On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  • 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.
  • INFO — INFO is INTEGER
    • = 0: successful exit
    • < 0: if INFO = -i, the i-th argument had an illegal value

👑 Author

The absolute legends behind this masterpiece:

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

🔍 Further Details:

Okay bestie, this is where it gets mathematically iconic. Strap in. 💅

If UPLO = 'U', the matrix Q is represented as a product of elementary reflectors:

Q = H(n-1) . . . H(2) H(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(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).

If UPLO = 'L', the matrix Q is represented as a product of elementary reflectors:

Q = H(1) H(2) . . . H(n-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 and v(i+1) = 1; v(i+2:n) is stored on exit in A(i+2:n,i), and tau in TAU(i).

The contents of A on exit are illustrated by the following examples with n = 5:

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).

📌 Definition at line 191 of file zhetrd.f.

🧚 Author

Generated automatically by Doxygen for LAPACK.

✨ Source/version tea: this iconic page comes from LAPACK, Version 3.12.0, and it's literally the hetrd(3) page — periodt. 💅💖

📦 where this page comes from