SRC/zggrqf.f(3)

📦
version 3.12.1 · 7 versions
, in arch rolling

✨ SRC/zggrqf.f ✨

okay bestie, this is a page out of the LAPACK manual — specifically SRC/zggrqf.f — and it's literally the glow-up era of linear algebra. it's a Fortran subroutine doc, so grab a lil snack 🍓 and let's get into it, because this one is a whole vibe (a unitary, generalized-RQ vibe, to be specific).

🌸 SYNOPSIS 🌸

Functions/Subroutines

  • subroutine zggrqf (m, p, n, a, lda, taua, b, ldb, taub, work, lwork, info) — ZGGRQF, the main character 💅

🦋 Function/Subroutine Documentation 🦋

subroutine zggrqf (integer m, integer p, integer n, complex*16, dimension( lda, * ) a, integer lda, complex*16, dimension( * ) taua, complex*16, dimension( ldb, * ) b, integer ldb, complex*16, dimension( * ) taub, complex*16, dimension( * ) work, integer lwork, integer info)

ZGGRQF — yes, that's the name, and yes, it ate. ✨

💜 Purpose:

ok so here's the tea, no cap: ZGGRQF computes a generalized RQ factorization of an M-by-N matrix A and a P-by-N matrix B:

      A = R*Q,        B = Z*T*Q,

where Q is an N-by-N unitary matrix, Z is a P-by-P unitary matrix, and R and T assume one of the forms:

if M <= N,  R = ( 0  R12 ) M,   or if M > N,  R = ( R11 ) M-N,
                 N-M  M                           ( R21 ) N
                                                    N

where R12 or R21 is upper triangular, and

if P >= N,  T = ( T11 ) N  ,   or if P < N,  T = ( T11  T12 ) P,
                (  0  ) P-N                         P   N-P
                   N

where T11 is upper triangular.

in particular (and this is the part that's giving main character energy 🔥), if B is square and nonsingular, the GRQ factorization of A and B implicitly gives the RQ factorization of A*inv(B):

             A*inv(B) = (R*inv(T))*Z**H

where inv(B) denotes the inverse of the matrix B, and Z**H denotes the conjugate transpose of the matrix Z.

🎀 Parameters 🎀

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

M is an INTEGER, bestie. it's how many rows A has. and M >= 0, periodt.

  • P
P is INTEGER
The number of rows of the matrix B.  P >= 0.

P is an INTEGER. number of rows of B. P >= 0, iykyk.

  • N
N is INTEGER
The number of columns of the matrices A and B. N >= 0.

N is an INTEGER. columns of both A and B, shared queen. N >= 0.

  • A
A is COMPLEX*16 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 TAUA, represent the unitary
matrix Q as a product of elementary reflectors (see Further
Details).

A is a COMPLEX*16 array, dimension (LDA,N). on entry it's the M-by-N matrix A; on exit it's holding R (upper triangle of A(1:M,N-M+1:N) if M <= N, or the upper trapezoidal situation on and above the (M-N)-th subdiagonal if M > N), and the leftovers + TAUA are doing the ✨represent-the-unitary-matrix-Q✨ thing. see Further Details, babe.

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

INTEGER, leading dimension of A. LDA >= max(1,M). don't test it. 🙈

  • TAUA
TAUA is COMPLEX*16 array, dimension (min(M,N))
The scalar factors of the elementary reflectors which
represent the unitary matrix Q (see Further Details).

COMPLEX*16 array, dimension (min(M,N)). these are the scalar factors of the elementary reflectors representing Q. iconic little scalars. 💫

  • B
B is COMPLEX*16 array, dimension (LDB,N)
On entry, the P-by-N matrix B.
On exit, the elements on and above the diagonal of the array
contain the min(P,N)-by-N upper trapezoidal matrix T (T is
upper triangular if P >= N); the elements below the diagonal,
with the array TAUB, represent the unitary matrix Z as a
product of elementary reflectors (see Further Details).

COMPLEX*16 array, dimension (LDB,N). entry: the P-by-N matrix B. exit: on-and-above the diagonal you get the min(P,N)-by-N upper trapezoidal T (upper triangular if P >= N, slay), and everything below the diagonal plus TAUB reps the unitary Z. 🦋

  • LDB
LDB is INTEGER
The leading dimension of the array B. LDB >= max(1,P).

INTEGER, leading dimension of B. LDB >= max(1,P).

  • TAUB
TAUB is COMPLEX*16 array, dimension (min(P,N))
The scalar factors of the elementary reflectors which
represent the unitary matrix Z (see Further Details).

COMPLEX*16 array, dimension (min(P,N)). scalar factors of the elementary reflectors that represent Z. TAUA's sister, equally iconic. 💜

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

COMPLEX*16 array, dimension (MAX(1,LWORK)). on exit, if INFO = 0, then WORK(1) spills the optimal LWORK. very helpful of it. 🫶

  • LWORK
LWORK is INTEGER
The dimension of the array WORK. LWORK >= max(1,N,M,P).
For optimum performance LWORK >= max(N,M,P)*max(NB1,NB2,NB3),
where NB1 is the optimal blocksize for the RQ factorization
of an M-by-N matrix, NB2 is the optimal blocksize for the
QR factorization of a P-by-N matrix, and NB3 is the optimal
blocksize for a call of ZUNMRQ.

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, the dimension of WORK. minimum is LWORK >= max(1,N,M,P). for optimum performance (highkey the goal 🌈) you want LWORK >= max(N,M,P)*max(NB1,NB2,NB3) — where NB1 is the optimal blocksize for the RQ factorization of an M-by-N matrix, NB2 is the optimal blocksize for the QR factorization of a P-by-N matrix, and NB3 is the optimal blocksize for a call of ZUNMRQ.

and if LWORK = -1, it's a workspace query, bestie: the routine only calculates the optimal size of the WORK array, returns that value as the first entry of WORK, and XERBLA issues no error message about LWORK. it's a whole different mode. 💅

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

INTEGER. = 0 means successful exit (we love that for us 🎉); < 0 means if INFO=-i, the i-th argument had an illegal value — so go check your args, not me. 💀

👑 Author

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

the whole squad. absolute legends, all four. 🫶

⭐ Further Details:

so the matrix Q is represented as a product of elementary reflectors:

Q = H(1) H(2) . . . H(k), where k = min(m,n).

each H(i) has the form

H(i) = I - taua * v * v**H

where taua is a complex scalar, and v is a complex vector with v(n-k+i+1:n) = 0 and v(n-k+i) = 1; v(1:n-k+i-1) is stored on exit in A(m-k+i,1:n-k+i-1), and taua in TAUA(i).

  • to form Q explicitly, use LAPACK subroutine ZUNGRQ.
  • to use Q to update another matrix, use LAPACK subroutine ZUNMRQ.

and the matrix Z is represented as a product of elementary reflectors

Z = H(1) H(2) . . . H(k), where k = min(p,n).

each H(i) has the form

H(i) = I - taub * v * v**H

where taub is a complex scalar, and v is a complex vector with v(1:i-1) = 0 and v(i) = 1; v(i+1:p) is stored on exit in B(i+1:p,i), and taub in TAUB(i).

  • to form Z explicitly, use LAPACK subroutine ZUNGQR.
  • to use Z to update another matrix, use LAPACK subroutine ZUNMQR.

Definition at line 212 of file zggrqf.f.

🌈 Author

generated automatically by Doxygen for LAPACK from the source code. it was born, not written. 🧚

okay that's the whole page, bestie — no skips, no summaries, we kept every single reflector. 🎀

this was LAPACK, Version 3.12.0, from SRC/zggrqf.f(3) — so cute, so unitary, so done. byeeee 💖✨
📦 where this page comes from