ungrq(3)

📦
version 3.12.1 · 9 versions
, in arch rolling

✨ ungrq(3) ✨ — Library Functions Manual 🎀

okay bestie, buckle up, because this whole page is about four little Fortran icons whose entire job is: take the sneaky compressed output of a ?gerqf call and expand it back into a full, gorgeous, orthonormal-rows matrix Q. it's giving "glow-up: restored edition" 💅

the gang's all here: cungrq, dorgrq, sorgrq, zungrq. one per data type. no cap.

🌸 NAME 🌸

ungrq — {un,or}grq: generate explicit Q from gerqf 🔥

like, the {un,or} is doing so much work there — un for the complex ones, or for the real ones, iykyk.

🦋 SYNOPSIS 🦋

✨ Functions ✨

here's the whole crew in their short form, exactly as written:

subroutine cungrq (m, n, k, a, lda, tau, work, lwork, info)
CUNGRQ
subroutine dorgrq (m, n, k, a, lda, tau, work, lwork, info)
DORGRQ
subroutine sorgrq (m, n, k, a, lda, tau, work, lwork, info)
SORGRQ
subroutine zungrq (m, n, k, a, lda, tau, work, lwork, info)
ZUNGRQ

and their fully-typed, all-dressed-up versions:

subroutine cungrq (integer m, integer n, integer k, complex, dimension( lda, * ) a, integer lda, complex, dimension( * ) tau, complex, dimension( * ) work, integer lwork, integer info)
subroutine dorgrq (integer m, integer n, integer k, double precision, dimension( lda, * ) a, integer lda, double precision, dimension( * ) tau, double precision, dimension( * ) work, integer lwork, integer info)
subroutine sorgrq (integer m, integer n, integer k, real, dimension( lda, * ) a, integer lda, real, dimension( * ) tau, real, dimension( * ) work, integer lwork, integer info)
subroutine zungrq (integer m, integer n, integer k, complex*16, dimension( lda, * ) a, integer lda, complex*16, dimension( * ) tau, complex*16, dimension( * ) work, integer lwork, integer info)

💜 Detailed Description 💜

okay so this section is basically just a signpost — the actual tea is all in Function Documentation below. the descriptions here are the formal one-liners for each routine: CUNGRQ, DORGRQ, SORGRQ, ZUNGRQ.

👑 Function Documentation 👑

🧚 subroutine cungrq — CUNGRQ

subroutine cungrq (integer m, integer n, integer k, complex, dimension( lda, * ) a, integer lda, complex, dimension( * ) tau, complex, dimension( * ) work, integer lwork, integer info)

🌟 Purpose 🌟

CUNGRQ builds an M-by-N complex matrix Q with orthonormal rows, and Q is defined as the last M rows of a product of K elementary reflectors of order N:

Q  =  H(1)**H H(2)**H . . . H(k)**H

exactly as returned by CGERQF. note the **H everywhere — conjugate transpose is the main character here, periodt. 💅

🍓 Parameters 🍓

  • M — M is INTEGER. the number of rows of the matrix Q. M >= 0. zero rows? valid. iconic. 💀
  • N — N is INTEGER. the number of columns of the matrix Q. N >= M. so it's a wide-ish or square-ish situation, never narrower than it is tall.
  • K — K is INTEGER. the number of elementary reflectors whose product defines the matrix Q. M >= K >= 0.
  • A — A is COMPLEX array, dimension (LDA,N).
    • on entry: the (m-k+i)-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by CGERQF in the last k rows of its array argument A.
    • on exit: the M-by-N matrix Q. glow-up complete ✨
  • LDA — LDA is INTEGER. the first dimension of the array A. LDA >= max(1,M).
  • TAU — TAU is COMPLEX array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by CGERQF.
  • WORK — WORK is COMPLEX array, dimension (MAX(1,LWORK)). on exit, if INFO = 0, WORK(1) returns the optimal LWORK. (she's telling you her ideal size, respect it.)
  • LWORK — LWORK is INTEGER. the dimension of the array WORK. LWORK >= max(1,M). for optimum performance LWORK >= M*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. so don't come for her when she stays quiet, she's literally just answering your question.
  • INFO — INFO is INTEGER.
    • = 0: successful exit 🎉
    • < 0: if INFO = -i, the i-th argument has an illegal value 💀

💖 Author 💖

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

📌 Definition 📌

Definition at line 127 of file cungrq.f.

🦋 subroutine dorgrq — DORGRQ

subroutine dorgrq (integer m, integer n, integer k, double precision, dimension( lda, * ) a, integer lda, double precision, dimension( * ) tau, double precision, dimension( * ) work, integer lwork, integer info)

🌟 Purpose 🌟

DORGRQ builds an M-by-N real matrix Q with orthonormal rows, defined as the last M rows of a product of K elementary reflectors of order N:

Q  =  H(1) H(2) . . . H(k)

as returned by DGERQF. and bestie — notice there's no **H up in here. real matrices, real vibes, no conjugate transpose needed. 🫶

🍓 Parameters 🍓

  • M — M is INTEGER. the number of rows of the matrix Q. M >= 0.
  • N — N is INTEGER. the number of columns of the matrix Q. N >= M.
  • K — K is INTEGER. the number of elementary reflectors whose product defines the matrix Q. M >= K >= 0.
  • A — A is DOUBLE PRECISION array, dimension (LDA,N).
    • on entry: the (m-k+i)-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by DGERQF in the last k rows of its array argument A.
    • on exit: the M-by-N matrix Q.
  • LDA — LDA is INTEGER. the first dimension of the array A. LDA >= max(1,M).
  • TAU — TAU is DOUBLE PRECISION array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by DGERQF.
  • 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 >= max(1,M). for optimum performance LWORK >= M*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 has an illegal value

💖 Author 💖

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

📌 Definition 📌

Definition at line 127 of file dorgrq.f.

🎀 subroutine sorgrq — SORGRQ

subroutine sorgrq (integer m, integer n, integer k, real, dimension( lda, * ) a, integer lda, real, dimension( * ) tau, real, dimension( * ) work, integer lwork, integer info)

🌟 Purpose 🌟

SORGRQ builds an M-by-N real matrix Q with orthonormal rows, defined as the last M rows of a product of K elementary reflectors of order N:

Q  =  H(1) H(2) . . . H(k)

as returned by SGERQF. single precision this time, same flawless energy. ⭐

🍓 Parameters 🍓

  • M — M is INTEGER. the number of rows of the matrix Q. M >= 0.
  • N — N is INTEGER. the number of columns of the matrix Q. N >= M.
  • K — K is INTEGER. the number of elementary reflectors whose product defines the matrix Q. M >= K >= 0.
  • A — A is REAL array, dimension (LDA,N).
    • on entry: the (m-k+i)-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by SGERQF in the last k rows of its array argument A.
    • on exit: the M-by-N matrix Q.
  • LDA — LDA is INTEGER. the first dimension of the array A. LDA >= max(1,M).
  • TAU — TAU is REAL array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by SGERQF.
  • 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 >= max(1,M). for optimum performance LWORK >= M*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 has an illegal value

💖 Author 💖

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

📌 Definition 📌

Definition at line 127 of file sorgrq.f.

🌈 subroutine zungrq — ZUNGRQ

subroutine zungrq (integer m, integer n, integer k, complex*16, dimension( lda, * ) a, integer lda, complex*16, dimension( * ) tau, complex*16, dimension( * ) work, integer lwork, integer info)

🌟 Purpose 🌟

ZUNGRQ builds an M-by-N complex matrix Q with orthonormal rows — the last M rows of a product of K elementary reflectors of order N, bestie:

Q  =  H(1)**H H(2)**H . . . H(k)**H

as returned by ZGERQF. double-complex, double-iconic, conjugate transposes absolutely everywhere. 💜

🍓 Parameters 🍓

  • M — M is INTEGER. the number of rows of the matrix Q. M >= 0.
  • N — N is INTEGER. the number of columns of the matrix Q. N >= M.
  • K — K is INTEGER. the number of elementary reflectors whose product defines the matrix Q. M >= K >= 0.
  • A — A is COMPLEX*16 array, dimension (LDA,N).
    • on entry: the (m-k+i)-th row must contain the vector which defines the elementary reflector H(i), for i = 1,2,...,k, as returned by ZGERQF in the last k rows of its array argument A.
    • on exit: the M-by-N matrix Q.
  • LDA — LDA is INTEGER. the first dimension of the array A. LDA >= max(1,M).
  • TAU — TAU is COMPLEX*16 array, dimension (K). TAU(i) must contain the scalar factor of the elementary reflector H(i), as returned by ZGERQF.
  • 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… and okay this one's got a whole saga attached, hold that thought 👀

LWORK 🌸

so LWORK is an INTEGER bestie, and it's literally just the dimension of the array WORK. the vibe check on it is:

  • LWORK >= max(1,M) — that's the bare minimum, no skipping 💅
  • for optimum performance you want LWORK >= M*NB, where NB is the optimal blocksize (yes she has a whole optimal blocksize, main character energy fr fr)

and now the iconic part — 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 — get this — no error message related to LWORK is issued by XERBLA. so she's not gonna yell at you for it. periodt.

INFO ✨

INFO is an INTEGER and it's your little report card 📋

  • = 0: successful exit 🎉 slay
  • < 0: if INFO = -i, the i-th argument has an illegal value 😭 (so like, check your args bestie)
heads up: a negative INFO is not a crash, it's just the routine telling you which argument it's side-eyeing. the i tells you the position. iykyk.

👑 Author

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

Definition at line 127 of file zungrq.f.

🫶 Author

Generated automatically by Doxygen for LAPACK from the source code.

okay that's the whole page bestie, you're free to go 💖 this gorgeous thing is from the LAPACK source, version 3.12.0, and it's the ungrq(3) man page — go be iconic with it 🦋✨🎀

📦 where this page comes from