CGERQF(3)

📦 version 3.12.0, in opensuse-leap 16.0

💅 CGERQF(3) — bestie, let's factor this ✨

okay so this page is literally from LAPACK Version 3.12.0, and the file it lives in is cgerqf.f (that's .../SRC/cgerqf.f in the source tree, iykyk). It's a library functions manual entry, and honestly? It ate. Let's get into it 🫶

🌸 NAME 🌸

/home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/SRC/cgerqf.f

that's the whole name, bestie. it's giving "my full government name is a file path" 😭 iconic though.

🦋 SYNOPSIS 🦋

Functions/Subroutines

subroutine CGERQF (m, n, a, lda, tau, work, lwork, info)
    CGERQF

yes that's a subroutine named CGERQF calling itself in the listing. no notes. main character energy 💅

⭐ Function/Subroutine Documentation ⭐

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

🎀 Purpose 🎀

okay so here's the whole vibe, straight from the source comment block:

!>
!> CGERQF computes an RQ factorization of a complex M-by-N matrix A:
!> A = R * Q.
!>

that's it. that's the whole job. A = R * Q. slay 🔥

💖 Parameters 💖

M

!>          M is INTEGER
!>          The number of rows of the matrix A.  M >= 0.
!>

your row count. M has to be >= 0, no negative row nonsense allowed 🙈

N

!>          N is INTEGER
!>          The number of columns of the matrix A.  N >= 0.
!>

your column count. N >= 0 too. everybody be non-negative 💜

A

!>          A is COMPLEX array, dimension (LDA,N)
!>          On entry, the M-by-N matrix A.
!>          On exit,
!>          if m <= n, the upper triangle of the subarray
!>          A(1:m,n-m+1:n) contains the M-by-M upper triangular matrix R;
!>          if m >= n, the elements on and above the (m-n)-th subdiagonal
!>          contain the M-by-N upper trapezoidal matrix R;
!>          the remaining elements, with the array TAU, represent the
!>          unitary matrix Q as a product of min(m,n) elementary
!>          reflectors (see Further Details).
!>

this one's the icon, the main character, the whole plot 👑 It's a COMPLEX array, dimension (LDA,N).

  • On entry? it's just the M-by-N matrix A. cute, simple.
  • On exit it's a whole glow-up:
    • if m <= n, the upper triangle of the subarray A(1:m,n-m+1:n) holds the M-by-M upper triangular matrix R;
    • if m >= n, the elements on and above the (m-n)-th subdiagonal hold the M-by-N upper trapezoidal matrix R;
    • and the remaining elements, together with the array TAU, represent the unitary matrix Q as a product of min(m,n) elementary reflectors (see Further Details, bestie, it's right down there ⬇️).

LDA

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

the leading dimension of A. rule is LDA >= max(1,M). no cap, respect the leading dimension 🫶

TAU

!>          TAU is COMPLEX array, dimension (min(M,N))
!>          The scalar factors of the elementary reflectors (see Further
!>          Details).
!>

COMPLEX array, dimension (min(M,N)). it's holding the scalar factors of the elementary reflectors. the details? Further. 💀

WORK

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

COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, then WORK(1) returns the optimal LWORK. it's giving "i brought receipts" ✨

LWORK

!>          LWORK is INTEGER
!>          The dimension of the array WORK.
!>          LWORK >= 1, if MIN(M,N) = 0, and LWORK >= M, otherwise.
!>          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.
!>

INTEGER, dimension of the WORK array. the rules, bestie:

  • LWORK >= 1, if MIN(M,N) = 0, and LWORK >= M, otherwise.
  • For optimum performance LWORK >= M*NB, where NB is the optimal blocksize.
  • and here's the fun one 👀 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 like, -1 is the "just tell me the size, don't yell at me" mode 🎀

INFO

!>          INFO is INTEGER
!>          = 0:  successful exit
!>          < 0:  if INFO = -i, the i-th argument had an illegal value
!>

INTEGER, the vibe check at the end 💀

  • = 0: successful exit. we love a clean finish 🌈
  • < 0: if INFO = -i, the i-th argument had an illegal value. somebody did NOT read the constraints 😭

👑 Author 👑

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

four institutions, one subroutine. the collab we didn't know we needed 🫶

🧚 Further Details 🧚

okay now the good part, the lore drop:

!>
!>  The matrix Q is represented as a product of elementary reflectors
!>
!>     Q = H(1)**H H(2)**H . . . H(k)**H, where k = min(m,n).
!>
!>  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(n-k+i+1:n) = 0 and v(n-k+i) = 1; conjg(v(1:n-k+i-1)) is stored on
!>  exit in A(m-k+i,1:n-k+i-1), and tau in TAU(i).
!>

so Q is a product of elementary reflectors: Q = H(1)**H H(2)**H . . . H(k)**H, where k = min(m,n).

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(n-k+i+1:n) = 0 and v(n-k+i) = 1.

and then — this is the part you screenshot 📸 — conjg(v(1:n-k+i-1)) is stored on exit in A(m-k+i,1:n-k+i-1), and tau in TAU(i). that's the storage tea. iykyk 💅

⭐ Definition at line 138 of file cgerqf.f. ⭐

like, line one-three-eight. precise. located. found her. 💖

🌸 Author 🌸

Generated automatically by Doxygen for LAPACK from the source code.

(yes, a robot wrote the docs. she still ate 🎀)

⚠️ friendly little heads-up bestie: everything above about dimensions and LWORK is straight from the page — especially that LWORK = -1 query mode, where XERBLA stays quiet about LWORK. don't get caught out there 🙈

and that's the page, bestie! 🦋 sign-off time: this was LAPACK, Version 3.12.0, living at /home/abui...RC/cgerqf.f(3) — go factor something and slay, periodt 💜✨

📦 where this page comes from