upmtr(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

💅 upmtr(3) — {up,op}mtr: multiply by Q from hptrd 🦋

okay bestie, so this is upmtr from the Library Functions Manual, and it's literally the family of routines that take the Q you got out of hptrd and smack it onto a matrix C. like, C gets overwritten. gone. replaced. slay 💅

it's giving "four subroutines, one job" energy: cupmtr, dopmtr, sopmtr, zupmtr — one per precision/flavor. let's get into it ✨

✨ SYNOPSIS ✨

🌸 Functions

  • subroutine cupmtr (side, uplo, trans, m, n, ap, tau, c, ldc, work, info) — CUPMTR
  • subroutine dopmtr (side, uplo, trans, m, n, ap, tau, c, ldc, work, info) — DOPMTR
  • subroutine sopmtr (side, uplo, trans, m, n, ap, tau, c, ldc, work, info) — SOPMTR
  • subroutine zupmtr (side, uplo, trans, m, n, ap, tau, c, ldc, work, info) — ZUPMTR

like clockwork, the same eleven args every single time 🫶

💖 Detailed Description 💖

ok so this is the Function Documentation section, and honestly it's just the four routines below going "hi bestie, here's my whole personality." main character energy, each of them 💀

🌈 subroutine cupmtr (character side, character uplo, character trans, integer m, integer n, complex, dimension( * ) ap, complex, dimension( * ) tau, complex, dimension( ldc, * ) c, integer ldc, complex, dimension( * ) work, integer info)

CUPMTR ✨

🎀 Purpose:

!>
!> CUPMTR overwrites the general complex M-by-N matrix C with
!>
!>                 SIDE = 'L'     SIDE = 'R'
!> TRANS = 'N':      Q * C          C * Q
!> TRANS = 'C':      Q**H * C       C * Q**H
!>
!> where Q is a complex unitary matrix of order nq, with nq = m if
!> SIDE = 'L' and nq = n if SIDE = 'R'. Q is defined as the product of
!> nq-1 elementary reflectors, as returned by CHPTRD using packed
!> storage:
!>
!> if UPLO = 'U', Q = H(nq-1) . . . H(2) H(1);
!>
!> if UPLO = 'L', Q = H(1) H(2) . . . H(nq-1).
!>

so real talk: Q is this complex unitary matrix of order nq, where nq = m if SIDE = 'L' and nq = n if SIDE = 'R'. and Q is built from nq-1 elementary reflectors that CHPTRD handed you, in packed storage. 😭 the ordering flips depending on UPLO, so watch out:

  • UPLO = 'U' → Q = H(nq-1) . . . H(2) H(1)
  • UPLO = 'L' → Q = H(1) H(2) . . . H(nq-1)

🧚 Parameters

  • SIDE — SIDE is CHARACTER*1
    • = 'L': apply Q or Q**H from the Left;
    • = 'R': apply Q or Q**H from the Right.
  • UPLO — UPLO is CHARACTER*1
    • = 'U': Upper triangular packed storage used in previous call to CHPTRD;
    • = 'L': Lower triangular packed storage used in previous call to CHPTRD.
  • TRANS — TRANS is CHARACTER*1
    • = 'N': No transpose, apply Q;
    • = 'C': Conjugate transpose, apply Q**H.
  • M — M is INTEGER. The number of rows of the matrix C. M >= 0.
  • N — N is INTEGER. The number of columns of the matrix C. N >= 0.
  • AP — AP is COMPLEX array, dimension
(M*(M+1)/2) if SIDE = 'L'
(N*(N+1)/2) if SIDE = 'R'

The vectors which define the elementary reflectors, as returned by CHPTRD. ⚠️ AP is modified by the routine but restored on exit — so it takes a little field trip and comes right back, no cap.

  • TAU — TAU is COMPLEX array, dimension (M-1) if SIDE = 'L' or (N-1) if SIDE = 'R'. TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CHPTRD.
  • C — C is COMPLEX array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q 👑 (yes, it's gone, that's the whole point).
  • LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
  • WORK — WORK is COMPLEX array, dimension
(N) if SIDE = 'L'
(M) if SIDE = 'R'
  • 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.

Definition at line 148 of file cupmtr.f.

🌸 subroutine dopmtr (character side, character uplo, character trans, integer m, integer n, double precision, dimension( * ) ap, double precision, dimension( * ) tau, double precision, dimension( ldc, * ) c, integer ldc, double precision, dimension( * ) work, integer info)

DOPMTR ✨

🎀 Purpose:

!>
!> DOPMTR overwrites the general real M-by-N matrix C with
!>
!>                 SIDE = 'L'     SIDE = 'R'
!> TRANS = 'N':      Q * C          C * Q
!> TRANS = 'T':      Q**T * C       C * Q**T
!>
!> where Q is a real orthogonal matrix of order nq, with nq = m if
!> SIDE = 'L' and nq = n if SIDE = 'R'. Q is defined as the product of
!> nq-1 elementary reflectors, as returned by DSPTRD using packed
!> storage:
!>
!> if UPLO = 'U', Q = H(nq-1) . . . H(2) H(1);
!>
!> if UPLO = 'L', Q = H(1) H(2) . . . H(nq-1).
!>

same vibe, but real this time — Q is a real orthogonal matrix of order nq, nq = m when SIDE = 'L' and nq = n when SIDE = 'R'. it's the product of nq-1 elementary reflectors from DSPTRD, packed storage, and the order flips like:

  • UPLO = 'U' → Q = H(nq-1) . . . H(2) H(1)
  • UPLO = 'L' → Q = H(1) H(2) . . . H(nq-1)

🧚 Parameters

  • SIDE — SIDE is CHARACTER*1
    • = 'L': apply Q or Q**T from the Left;
    • = 'R': apply Q or Q**T from the Right.
  • UPLO — UPLO is CHARACTER*1
    • = 'U': Upper triangular packed storage used in previous call to DSPTRD;
    • = 'L': Lower triangular packed storage used in previous call to DSPTRD.
  • TRANS — TRANS is CHARACTER*1
    • = 'N': No transpose, apply Q;
    • = 'T': Transpose, apply Q**T.
  • M — M is INTEGER. The number of rows of the matrix C. M >= 0.
  • N — N is INTEGER. The number of columns of the matrix C. N >= 0.
  • AP — AP is DOUBLE PRECISION array, dimension
(M*(M+1)/2) if SIDE = 'L'
(N*(N+1)/2) if SIDE = 'R'

The vectors which define the elementary reflectors, as returned by DSPTRD. ⚠️ AP is modified by the routine but restored on exit.

  • TAU — TAU is DOUBLE PRECISION array, dimension (M-1) if SIDE = 'L' or (N-1) if SIDE = 'R'. TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by DSPTRD.
  • C — C is DOUBLE PRECISION array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**T*C or C*Q**T or C*Q 👑
  • LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
  • WORK — WORK is DOUBLE PRECISION array, dimension
(N) if SIDE = 'L'
(M) if SIDE = 'R'
  • 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.

Definition at line 148 of file dopmtr.f.

🌈 subroutine sopmtr (character side, character uplo, character trans, integer m, integer n, real, dimension( * ) ap, real, dimension( * ) tau, real, dimension( ldc, * ) c, integer ldc, real, dimension( * ) work, integer info)

SOPMTR ✨

🎀 Purpose:

!>
!> SOPMTR overwrites the general real M-by-N matrix C with
!>
!>                 SIDE = 'L'     SIDE = 'R'
!> TRANS = 'N':      Q * C          C * Q
!> TRANS = 'T':      Q**T * C       C * Q**T
!>
!> where Q is a real orthogonal matrix of order nq, with nq = m if
!> SIDE = 'L' and nq = n if SIDE = 'R'. Q is defined as the product of
!> nq-1 elementary reflectors, as returned by SSPTRD using packed
!> storage:
!>
!> if UPLO = 'U', Q = H(nq-1) . . . H(2) H(1);
!>
!> if UPLO = 'L', Q = H(1) H(2) . . . H(nq-1).
!>

the single-precision real sibling, and it's literally the same storyline: real orthogonal Q, order nq = m for SIDE = 'L' / nq = n for SIDE = 'R', product of nq-1 elementary reflectors from SSPTRD, packed storage:

  • UPLO = 'U' → Q = H(nq-1) . . . H(2) H(1)
  • UPLO = 'L' → Q = H(1) H(2) . . . H(nq-1)

🧚 Parameters

  • SIDE — SIDE is CHARACTER*1
    • = 'L': apply Q or Q**T from the Left;
    • = 'R': apply Q or Q**T from the Right.
  • UPLO — UPLO is CHARACTER*1
    • = 'U': Upper triangular packed storage used in previous call to SSPTRD;
    • = 'L': Lower triangular packed storage used in previous call to SSPTRD.
  • TRANS — TRANS is CHARACTER*1
    • = 'N': No transpose, apply Q;
    • = 'T': Transpose, apply Q**T.
  • M — M is INTEGER. The number of rows of the matrix C. M >= 0.
  • N — N is INTEGER. The number of columns of the matrix C. N >= 0.
  • AP — AP is REAL array, dimension
(M*(M+1)/2) if SIDE = 'L'
(N*(N+1)/2) if SIDE = 'R'

The vectors which define the elementary reflectors, as returned by SSPTRD. ⚠️ AP is modified by the routine but restored on exit.

  • TAU — TAU is REAL array, dimension (M-1) if SIDE = 'L' or (N-1) if SIDE = 'R'. TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SSPTRD.
  • C — C is REAL array, dimension (LDC,N). On entry, the M-by-N matrix C. On exit, C is overwritten by Q*C or Q**T*C or C*Q**T or C*Q 👑
  • LDC — LDC is INTEGER. The leading dimension of the array C. LDC >= max(1,M).
  • WORK — WORK is REAL array, dimension
(N) if SIDE = 'L'
(M) if SIDE = 'R'
  • 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.

Definition at line 148 of file sopmtr.f.

ok bestie that's where part 1 wraps the routine docs — but hold up, we are not done 🫶 there's more coming, so don't go anywhere 💖

   subroutine zupmtr (character side, character uplo, character trans, integer
       m, integer n, complex*16, dimension( * ) ap, complex*16, dimension( * )
       tau, complex*16, dimension( ldc, * ) c, integer ldc, complex*16,
       dimension( * ) work, integer info)
       ZUPMTR

✨ Purpose ✨

Bestie. Okay so here's the whole vibe of ZUPMTR: it overwrites the general complex M-by-N matrix C with one of these four looks 👇

                SIDE = 'L'     SIDE = 'R'
TRANS = 'N':      Q * C          C * Q
TRANS = 'C':      Q**H * C       C * Q**H

where Q is a complex unitary matrix of order nq, with nq = m if SIDE = 'L' and nq = n if SIDE = 'R'. And Q is defined as the product of nq-1 elementary reflectors, exactly as returned by ZHPTRD using packed storage:

if UPLO = 'U', Q = H(nq-1) . . . H(2) H(1);

if UPLO = 'L', Q = H(1) H(2) . . . H(nq-1).

It's giving "I'm just the reflector messenger" 💅 — you bring the reflectors, ZUPMTR does the multiplying. Slay.

🎀 Parameters 🎀

Get comfy, we're going through every single one, no skips, no cap 🫶

SIDE

SIDE is CHARACTER*1 and it's literally just telling us which side to hit from:

  • = 'L' — apply Q or Q**H from the Left;
  • = 'R' — apply Q or Q**H from the Right.

Pick a side, bestie. Left or right. Main character decision 🔥

UPLO

UPLO is CHARACTER*1 and it's here to remind us how the packed storage was laid out in the previous call to ZHPTRD:

  • = 'U' — Upper triangular packed storage used in previous call to ZHPTRD;
  • = 'L' — Lower triangular packed storage used in previous call to ZHPTRD.

It has to match what you did before, iykyk — this is a callback, not a reboot 💀

TRANS

TRANS is CHARACTER*1, the transpose vibe check:

  • = 'N' — No transpose, apply Q;
  • = 'C' — Conjugate transpose, apply Q**H.

Two options, both iconic, choose wisely ✨

M

M is INTEGER — the number of rows of the matrix C, and M >= 0. Not optional, the math said so 🧚

N

N is INTEGER — the number of columns of the matrix C, and N >= 0. Same energy, same rules 🌸

AP

AP is COMPLEX*16 array, with dimension:

(M*(M+1)/2) if SIDE = 'L'
(N*(N+1)/2) if SIDE = 'R'

These are the vectors which define the elementary reflectors, as returned by ZHPTRD. And important little detail: AP is modified by the routine but restored on exit — so she borrows your data, plays with it, puts it back exactly how she found it. Respectful queen behavior 👑💖

TAU

TAU is COMPLEX*16 array, dimension (M-1) if SIDE = 'L' or (N-1) if SIDE = 'R'.

TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZHPTRD. So like, every reflector has its little scalar bestie and they have to match up 🎀

C

C is COMPLEX*16 array, dimension (LDC,N):

  • On entry, the M-by-N matrix C.
  • On exit, C is overwritten by Q*C or Q**H*C or C*Q**H or C*Q.

Whichever of the four it is depends on SIDE and TRANS, obvi. Your original C? Gone. Transformed. Glow-up complete 🦋

LDC

LDC is INTEGER — the leading dimension of the array C, and it must satisfy LDC >= max(1,M). Rules are rules, bestie 😌

WORK

WORK is COMPLEX*16 array, dimension:

(N) if SIDE = 'L'
(M) if SIDE = 'R'

Scratch space. Give her room to work 🫶

INFO

INFO is INTEGER, the final report card:

  • = 0 — successful exit, we love a clean run ✨
  • < 0 — if INFO = -i, the i-th argument had an illegal value. So like, if INFO = -3, go look at the third argument and apologize to it 🙈

🌈 Author 🌈

The absolute legends who brought you this:

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

Definition at line 148 of file zupmtr.f. 🎯

⭐ Author ⭐

Generated automatically by Doxygen for LAPACK from the source code. Not me, not you, the robot did it 🤖💜

Okay that's the whole page, bestie!! Go forth and multiply your matrices 💅🔥 This was LAPACK Version 3.12.0, upmtr(3), and the whole thing is stamped with the source/version and date vibes from the footer — consider it your cute little sign-off: version three-point-twelve-point-oh, periodt. 🎀🦋💖

📦 where this page comes from