hbtrd(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

🌸 NAME 🌸

hbtrd(3) — straight out of the Library Functions Manual, babes 📚 — and the actual name line is:

hbtrd — {hb,sb}trd: reduction to tridiagonal ✨

okay so real talk: this is the family page for the four routines that take your band matrix and reduce it to tridiagonal form. It's giving "glow-up arc". Let's go 💅

✨ SYNOPSIS ✨

🎀 Functions

  • chbtrd — the CHBTRD girlie 💜
  • dsbtrd — the DSBTRD girlie 💜
  • ssbtrd — the SSBTRD girlie 💜
  • zhbtrd — the ZHBTRD girlie 💜

and their signatures, exactly, no cap:

subroutine chbtrd (vect, uplo, n, kd, ab, ldab, d, e, q, ldq, work,
    info)
subroutine dsbtrd (vect, uplo, n, kd, ab, ldab, d, e, q, ldq, work,
    info)
subroutine ssbtrd (vect, uplo, n, kd, ab, ldab, d, e, q, ldq, work,
    info)
subroutine zhbtrd (vect, uplo, n, kd, ab, ldab, d, e, q, ldq, work,
    info)

🦋 Detailed Description 🦋

bestie the source literally has nothing under this heading. Empty. Void. Main-character silence 💀 so I'm not gonna invent lore, we're just heading straight into the function docs. iykyk.

👑 Function Documentation 👑

💜 subroutine chbtrd (character vect, character uplo, integer n, integer kd, complex, dimension( ldab, * ) ab, integer ldab, real, dimension( * ) d, real, dimension( * ) e, complex, dimension( ldq, * ) q, integer ldq, complex, dimension( * ) work, integer info)

CHBTRD

⭐ Purpose:

so what does she do? here's the word-for-word vibe:

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

complex Hermitian band in, real symmetric tridiagonal out. iconic transformation honestly 🔥

💅 Parameters

  • VECT — it's a CHARACTER*1 and it controls whether we even bother building Q:
    • = 'N': do not form Q;
    • = 'V': form Q;
    • = 'U': update a matrix X, by forming X*Q.
  • UPLO — also CHARACTER*1, picks which triangle you're feeding her:
    • = 'U': Upper triangle of A is stored;
    • = 'L': Lower triangle of A is stored.
  • N — INTEGER. The order of the matrix A. N >= 0. no negatives, bestie, that's literally not allowed 🫶
  • KD — INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0. your band width, basically ✨
  • AB — COMPLEX array, dimension (LDAB,N).

On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:

if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+kd).

On exit, the diagonal elements of AB are overwritten by the diagonal elements of the tridiagonal matrix T; if KD > 0, the elements on the first superdiagonal (if UPLO = 'U') or the first subdiagonal (if UPLO = 'L') are overwritten by the off-diagonal elements of T; the rest of AB is overwritten by values generated during the reduction.

⚠️ so like — she overwrites AB. your original data is gone-gone. not me warning you twice 💀
  • LDAB — INTEGER. The leading dimension of the array AB. LDAB >= KD+1. respect the boundary, queen 👑
  • D — REAL array, dimension (N). The diagonal elements of the tridiagonal matrix T. the actual stars of the show 💖
  • E — REAL array, dimension (N-1). The off-diagonal elements of the tridiagonal matrix T: E(i) = T(i,i+1) if UPLO = 'U'; E(i) = T(i+1,i) if UPLO = 'L'. she's short by one and that's correct 😌
  • Q — COMPLEX array, dimension (LDQ,N).

On entry, if VECT = 'U', then Q must contain an N-by-N matrix X; if VECT = 'N' or 'V', then Q need not be set.

On exit:

  • if VECT = 'V', Q contains the N-by-N unitary matrix Q;
  • if VECT = 'U', Q contains the product X*Q;
  • if VECT = 'N', the array Q is not referenced.

(yes she said "the unitary matrix Q" and also "Q" — same name, different energy, iykyk 🌈)

  • LDQ — INTEGER. The leading dimension of the array Q. LDQ >= 1, and LDQ >= N if VECT = 'V' or 'U'. read it twice, that second clause is the one people miss 🙈
  • WORK — COMPLEX array, dimension (N). scratch space, no notes ✨
  • INFO — 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:

!>
!> Modified by Linda Kaufman, Bell Labs.
!>

🎀 Definition at line 161 of file chbtrd.f.

💜 subroutine dsbtrd (character vect, character uplo, integer n, integer kd, double precision, dimension( ldab, * ) ab, integer ldab, double precision, dimension( * ) d, double precision, dimension( * ) e, double precision, dimension( ldq, * ) q, integer ldq, double precision, dimension( * ) work, integer info)

DSBTRD

⭐ Purpose:

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

double precision edition, and note she says Q**T — the transpose, not the conjugate transpose. details matter bestie 💅

💅 Parameters

  • VECT — CHARACTER*1:
    • = 'N': do not form Q;
    • = 'V': form Q;
    • = 'U': update a matrix X, by forming X*Q.
  • UPLO — CHARACTER*1:
    • = 'U': Upper triangle of A is stored;
    • = 'L': Lower triangle of A is stored.
  • N — INTEGER. The order of the matrix A. N >= 0.
  • KD — INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
  • AB — DOUBLE PRECISION array, dimension (LDAB,N).

On entry, the upper or lower triangle of the symmetric band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:

if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+kd).

On exit, the diagonal elements of AB are overwritten by the diagonal elements of the tridiagonal matrix T; if KD > 0, the elements on the first superdiagonal (if UPLO = 'U') or the first subdiagonal (if UPLO = 'L') are overwritten by the off-diagonal elements of T; the rest of AB is overwritten by values generated during the reduction.

⚠️ again: AB gets overwritten. you've been warned, gorgeous 🫶
  • LDAB — INTEGER. The leading dimension of the array AB. LDAB >= KD+1.
  • D — DOUBLE PRECISION array, dimension (N). The diagonal elements of the tridiagonal matrix T.
  • E — DOUBLE PRECISION array, dimension (N-1). The off-diagonal elements of the tridiagonal matrix T: E(i) = T(i,i+1) if UPLO = 'U'; E(i) = T(i+1,i) if UPLO = 'L'.
  • Q — DOUBLE PRECISION array, dimension (LDQ,N).

On entry, if VECT = 'U', then Q must contain an N-by-N matrix X; if VECT = 'N' or 'V', then Q need not be set.

On exit:

  • if VECT = 'V', Q contains the N-by-N orthogonal matrix Q;
  • if VECT = 'U', Q contains the product X*Q;
  • if VECT = 'N', the array Q is not referenced.
  • LDQ — INTEGER. The leading dimension of the array Q. LDQ >= 1, and LDQ >= N if VECT = 'V' or 'U'.
  • WORK — DOUBLE PRECISION array, dimension (N).
  • INFO — 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:

!>
!> Modified by Linda Kaufman, Bell Labs.
!>

🎀 Definition at line 161 of file dsbtrd.f.

💜 subroutine ssbtrd (character vect, character uplo, integer n, integer kd, real, dimension( ldab, * ) ab, integer ldab, real, dimension( * ) d, real, dimension( * ) e, real, dimension( ldq, * ) q, integer ldq, real, dimension( * ) work, integer info)

SSBTRD

⭐ Purpose:

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

same routine as DSBTRD but single precision — she's the REAL one and yes she's still that girl 🔥

💅 Parameters

  • VECT — CHARACTER*1:
    • = 'N': do not form Q;
    • = 'V': form Q;
    • = 'U': update a matrix X, by forming X*Q.
  • UPLO — CHARACTER*1:
    • = 'U': Upper triangle of A is stored;
    • = 'L': Lower triangle of A is stored.
  • N — INTEGER. The order of the matrix A. N >= 0.
  • KD — INTEGER. The number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. KD >= 0.
  • AB — REAL array, dimension (LDAB,N).

On entry, the upper or lower triangle of the symmetric band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:

if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
if UPLO = 'L', AB(1+i-j,j)    = A(i,j) for j<=i<=min(n,j+kd).

On exit, the diagonal elements of AB are overwritten by the diagonal elements of the tridiagonal matrix T; if KD > 0, the elements on the first superdiagonal (if UPLO = 'U') or the first subdiagonal (if UPLO = 'L') are overwritten by the off-diagonal elements of T; the rest of AB is overwritten by values generated during the reduction.

⚠️ yes, AB is still getting overwritten. it's a whole thing. protect your data, bestie 💀
  • LDAB — INTEGER. The leading dimension of the array AB. LDAB >= KD+1.
  • D — REAL array, dimension (N). The diagonal elements of the tridiagonal matrix T.
  • E — 🦋 (okay E's full glow-up, plus Q, LDQ, WORK, INFO, the author credits and the file line — all of that is literally continuing in part 2, we're stopping mid-parameter 💀 hold that thought, babe 🫶)
  • E (REAL array, dimension (N-1)) — the off-diagonal besties of the tridiagonal matrix T, aka the ✨side characters✨. Specifically: E(i) = T(i,i+1) if UPLO = 'U'; E(i) = T(i+1,i) if UPLO = 'L'. iykyk 💅
  • Q (REAL array, dimension (LDQ,N)) — okay so on entry, if VECT = 'U', then Q must contain an N-by-N matrix X; if VECT = 'N' or 'V', then Q need not be set (she's off duty, leave her alone 🙈).

On exit though? Different story:

  • if VECT = 'V', Q contains the N-by-N orthogonal matrix Q — main character energy 👑
  • if VECT = 'U', Q contains the product X*Q
  • if VECT = 'N', the array Q is not referenced. not even looked at. ghosted 💀
  • LDQ (INTEGER) — the leading dimension of the array Q. Rules are LDQ >= 1, and LDQ >= N if VECT = 'V' or 'U'. respect the constraints bestie 🫶
  • WORK (REAL array, dimension (N)) — her little scratchpad, she works hard so you don't have to 🌸
  • INFO (INTEGER) — the vibe check at the end ✨
    • = 0: successful exit, we ate 🎀
    • < 0: if INFO = -i, the i-th argument had an illegal value. not me getting caught lacking 😭

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details

Modified by Linda Kaufman, Bell Labs.

Definition at line 161 of file ssbtrd.f.

🌈 subroutine zhbtrd

The complex Hermitian sibling!! same gig, different dtype, she's literally iconic 💜

subroutine zhbtrd (character vect, character uplo, integer n, integer kd,
    complex*16, dimension( ldab, * ) ab, integer ldab, double precision,
    dimension( * ) d, double precision, dimension( * ) e, complex*16,
    dimension( ldq, * ) q, integer ldq, complex*16, dimension( * ) work,
    integer info)

ZHBTRD — yes that's her name, no we're not shortening it 💅

⭐ Purpose

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

so like. she takes your big messy Hermitian band matrix and turns it into a cute tidy tridiagonal one. a glow-up, honestly 🦋✨

🎀 Parameters

  • VECT (CHARACTER*1) — what do you want her to do with Q, bestie? decide now 🫶
    • = 'N': do not form Q;
    • = 'V': form Q;
    • = 'U': update a matrix X, by forming X*Q.
  • UPLO (CHARACTER*1) — which triangle of A are we even storing?
    • = 'U': Upper triangle of A is stored;
    • = 'L': Lower triangle of A is stored.
  • N (INTEGER) — the order of the matrix A. and she's serious about N >= 0 🍓
  • KD (INTEGER) — the number of superdiagonals of the matrix A if UPLO = 'U', or the number of subdiagonals if UPLO = 'L'. and again: KD >= 0. no cap ⭐
  • AB (COMPLEX*16 array, dimension (LDAB,N)) — this is the big one, pay attention 👀

On entry, the upper or lower triangle of the Hermitian band matrix A, stored in the first KD+1 rows of the array. The j-th column of A is stored in the j-th column of the array AB as follows:

  • if UPLO = 'U', AB(kd+1+i-j,j) = A(i,j) for max(1,j-kd)<=i<=j;
  • if UPLO = 'L', AB(1+i-j,j) = A(i,j) for j<=i<=min(n,j+kd).

On exit? Oh she replaces things, be warned 💀 the diagonal elements of AB are overwritten by the diagonal elements of the tridiagonal matrix T; if KD > 0, the elements on the first superdiagonal (if UPLO = 'U') or the first subdiagonal (if UPLO = 'L') are overwritten by the off-diagonal elements of T; and the rest of AB is overwritten by values generated during the reduction. so like. your input is gone, she's moved on, that's the deal 🙈

  • LDAB (INTEGER) — the leading dimension of the array AB. constraint check: LDAB >= KD+1. don't test her 🌸
  • D (DOUBLE PRECISION array, dimension (N)) — the diagonal elements of the tridiagonal matrix T. the main characters, fr fr 👑
  • E (DOUBLE PRECISION array, dimension (N-1)) — the off-diagonal elements of the tridiagonal matrix T: E(i) = T(i,i+1) if UPLO = 'U'; E(i) = T(i+1,i) if UPLO = 'L'. she's the supporting cast but she carries the plot 💜
  • Q (COMPLEX*16 array, dimension (LDQ,N)) — okay so on entry, if VECT = 'U', then Q must contain an N-by-N matrix X; if VECT = 'N' or 'V', then Q need not be set (she's resting, do not disturb 😴).

On exit:

  • if VECT = 'V', Q contains the N-by-N unitary matrix Q — note: unitary, not orthogonal, we're in complex land now bestie 🌈
  • if VECT = 'U', Q contains the product X*Q;
  • if VECT = 'N', the array Q is not referenced. not a single glance. 💀
  • LDQ (INTEGER) — the leading dimension of the array Q. the rules: LDQ >= 1, and LDQ >= N if VECT = 'V' or 'U'. respect it or she throws INFO at you 😭
  • WORK (COMPLEX*16 array, dimension (N)) — her little workspace. complex this time. she's doing complex math, give her the space 🧚
  • INFO (INTEGER) — the final verdict ✨
    • = 0: successful exit, slay, periodt 🎉
    • < 0: if INFO = -i, the i-th argument had an illegal value. you got called out, respectfully 🔥

👑 Author

Univ. of Tennessee

Univ. of California Berkeley

Univ. of Colorado Denver

NAG Ltd.

🔍 Further Details

Modified by Linda Kaufman, Bell Labs.

Definition at line 161 of file zhbtrd.f.

💖 Author (the meta one)

Generated automatically by Doxygen for LAPACK from the source code.

okay bestie that's the whole page 💅 both ssbtrd and zhbtrd, fully documented, no details left behind, we love a complete reference 🫶 this absolute icon of a page is from LAPACK, Version 3.12.0 (page hbtrd(3)), and it was lovingly auto-generated by Doxygen from the source code — so if you ever need to cite your source, that's the one. go forth and reduce your band matrices, you've got this 🌟🎀🦋

📦 where this page comes from