ggrqf(3)

πŸŽ€ ggrqf(3) β€” Library Functions Manual πŸŽ€

okay bestie, buckle up, because this is the ggrqf page β€” yes, the whole generalized RQ factor of it β€” and she is long. Grab a strawberry drink πŸ“ and let's go.


✨ NAME ✨

ggrqf β€” the generalized RQ factor. that's it, that's the name. short, sweet, iconic. πŸ‘‘


🌸 SYNOPSIS 🌸

πŸ’… Functions

subroutine cggrqf (m, p, n, a, lda, taua, b, ldb, taub, work, lwork,
    info)
    CGGRQF
subroutine dggrqf (m, p, n, a, lda, taua, b, ldb, taub, work, lwork,
    info)
    DGGRQF
subroutine sggrqf (m, p, n, a, lda, taua, b, ldb, taub, work, lwork,
    info)
    SGGRQF
subroutine zggrqf (m, p, n, a, lda, taua, b, ldb, taub, work, lwork,
    info)
    ZGGRQF

four flavors, one vibe β€” C, D, S, Z, pick your letter, slay. ✨


πŸ¦‹ Detailed Description πŸ¦‹

okay so this section is literally empty on the page. nothing here. we move. πŸ’€


πŸ”₯ Function Documentation πŸ”₯

πŸ’œ subroutine cggrqf

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

CGGRQF

🫢 Purpose:

!> β€” yes the comments keep their !>, that's just how she lives, no cap.

so basically CGGRQF 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 these forms β€” lowkey the shapes are the whole personality:

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 also:

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. ✨

and the flex? in particular, 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. it's giving math main character energy, honestly. πŸ‘‘

πŸŽ€ Parameters

  • M β€” M is INTEGER, the number of rows of the matrix A. constraint: M >= 0. no negativity allowed.
  • P β€” P is INTEGER, the number of rows of the matrix B. constraint: P >= 0.
  • N β€” N is INTEGER, the number of columns of the matrices A and B. constraint: N >= 0.
  • A β€” A is COMPLEX array, dimension (LDA,N). On entry, it's 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, together with the array TAUA, represent the unitary matrix Q as a product of elementary reflectors (see Further Details). πŸ¦‹
  • LDA β€” LDA is INTEGER, the leading dimension of the array A. constraint: LDA >= max(1,M).
  • TAUA β€” TAUA is COMPLEX array, dimension (min(M,N)). the scalar factors of the elementary reflectors which represent the unitary matrix Q (see Further Details).
  • B β€” B is COMPLEX 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, together with the array TAUB, represent the unitary matrix Z as a product of elementary reflectors (see Further Details). 🌈
  • LDB β€” LDB is INTEGER, the leading dimension of the array B. constraint: LDB >= max(1,P).
  • TAUB β€” TAUB is COMPLEX array, dimension (min(P,N)). the scalar factors of the elementary reflectors which represent the unitary matrix Z (see Further Details).
  • WORK β€” WORK is COMPLEX array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK. king behavior. πŸ‘‘
  • LWORK β€” LWORK is INTEGER, the dimension of the array WORK. constraint: 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 CUNMRQ. and bestie, listen: 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, she's just answering the question you asked. πŸ™ˆ
  • INFO β€” INFO is INTEGER, and it's the vibe check:
    • = 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.

like, an absolute supergroup of institutions. we stan. 🫢

⭐ Further Details:

!> β€” more reflective goodness incoming:

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 CUNGRQ. to use Q to update another matrix, use LAPACK subroutine CUNMRQ.

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 CUNGQR. to use Z to update another matrix, use LAPACK subroutine CUNMQR.

Definition at line 212 of file cggrqf.f. πŸ“


🧚 subroutine dggrqf

subroutine dggrqf (integer m, integer p, integer n, double precision,
    dimension( lda, * ) a, integer lda, double precision, dimension( * )
    taua, double precision, dimension( ldb, * ) b, integer ldb, double
    precision, dimension( * ) taub, double precision, dimension( * ) work,
    integer lwork, integer info)

DGGRQF

🫢 Purpose:

!> β€” same !> energy, different letter, we love consistency.

so DGGRQF 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 orthogonal matrix, Z is a P-by-P orthogonal 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, 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**T

where inv(B) denotes the inverse of the matrix B, and Z**T denotes the transpose of the matrix Z. (note: Z**T here, not Z**H β€” the real version is built different, literally.) πŸ”₯

πŸŽ€ Parameters

  • M β€” M is INTEGER, the number of rows of the matrix A. constraint: M >= 0.
  • P β€” P is INTEGER, the number of rows of the matrix B. constraint: P >= 0.
  • N β€” N is INTEGER, the number of columns of the matrices A and B. constraint: N >= 0.
  • A β€” A is DOUBLE PRECISION 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, together with the array TAUA, represent the orthogonal matrix Q as a product of elementary reflectors (see Further Details). πŸ¦‹
  • LDA β€” LDA is INTEGER, the leading dimension of the array A. constraint: LDA >= max(1,M).
  • TAUA β€” TAUA is DOUBLE PRECISION array, dimension (min(M,N)). the scalar factors of the elementary reflectors which represent the orthogonal matrix Q (see Further Details).
  • B β€” B is DOUBLE PRECISION 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, together with the array TAUB, represent the orthogonal matrix Z as a product of elementary reflectors (see Further Details). 🌈
  • LDB β€” LDB is INTEGER, the leading dimension of the array B. constraint: LDB >= max(1,P).
  • TAUB β€” TAUB is DOUBLE PRECISION array, dimension (min(P,N)). the scalar factors of the elementary reflectors which represent the orthogonal matrix Z (see Further Details).
  • WORK β€” WORK is DOUBLE PRECISION array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  • LWORK

First up, still inside dggrqf's parameter list β€” we're so back πŸ’…

  • LWORK β€” INTEGER. This is the dimension of the array WORK. The minimum is LWORK >= max(1,N,M,P). For optimum performance, 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 DORMRQ.
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. Literally a little vibe-check-only mode, no drama 😌
  • INFO β€” INTEGER. = 0: successful exit. < 0: if INF0= -i, the i-th argument had an illegal value. Yes bestie, the source spells it INF0 with a zero β€” we keep it exactly, no cap.

Author πŸ’–

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

Further Details 🧚

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**T

where taua is a real scalar, and v is a real 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 DORGRQ. To use Q to update another matrix, use LAPACK subroutine DORMRQ.

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**T

where taub is a real scalar, and v is a real 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 DORGQR. To use Z to update another matrix, use LAPACK subroutine DORMQR.

Definition at line 212 of file dggrqf.f.


✨ subroutine sggrqf ✨

subroutine sggrqf (integer m, integer p, integer n, real, dimension( lda, * ) a, integer lda, real, dimension( * ) taua, real, dimension( ldb, * ) b, integer ldb, real, dimension( * ) taub, real, dimension( * ) work, integer lwork, integer info)

SGGRQF is right here, same energy, different letter 🫢

Purpose πŸ’…

SGGRQF 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 orthogonal matrix, Z is a P-by-P orthogonal 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, 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**T

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

Parameters 🌸

  • M β€” INTEGER. The number of rows of the matrix A. M >= 0.
  • P β€” INTEGER. The number of rows of the matrix B. P >= 0.
  • N β€” INTEGER. The number of columns of the matrices A and B. N >= 0.
  • A β€” REAL 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 orthogonal matrix Q as a product of elementary reflectors (see Further Details).
  • LDA β€” INTEGER. The leading dimension of the array A. LDA >= max(1,M).
  • TAUA β€” REAL array, dimension (min(M,N)). The scalar factors of the elementary reflectors which represent the orthogonal matrix Q (see Further Details).
  • B β€” REAL 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 orthogonal matrix Z as a product of elementary reflectors (see Further Details).
  • LDB β€” INTEGER. The leading dimension of the array B. LDB >= max(1,P).
  • TAUB β€” REAL array, dimension (min(P,N)). The scalar factors of the elementary reflectors which represent the orthogonal matrix Z (see Further Details).
  • WORK β€” REAL array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
  • LWORK β€” 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 SORMRQ.
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. Same iconic query behavior, zero notes πŸ’€
  • INFO β€” INTEGER. = 0: successful exit. < 0: if INF0= -i, the i-th argument had an illegal value. Again: INF0, with a zero, we are not touching it πŸ™ˆ

Author πŸ’–

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

Further Details ✨

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**T

where taua is a real scalar, and v is a real 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 SORGRQ. To use Q to update another matrix, use LAPACK subroutine SORMRQ.

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**T

where taub is a real scalar, and v is a real 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 SORGQR. To use Z to update another matrix, use LAPACK subroutine SORMQR.

Definition at line 212 of file sggrqf.f.


πŸ¦‹ subroutine zggrqf πŸ¦‹

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 has entered the chat, and it's giving complex*16 royalty πŸ‘‘

Purpose πŸ’œ

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, 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 β€” INTEGER. The number of rows of the matrix A. M >= 0.
  • P β€” INTEGER. The number of rows of the matrix B. P >= 0.
  • N β€” INTEGER. The number of columns of the matrices A and B. N >= 0.

🫧 A 🫧

okay so A is a COMPLEX*16 array, dimension (LDA,N).

On entry? that's literally the M-by-N matrix A, bestie.

On exit it's giving two different eras depending on your shapes:

  • 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 TAUA, represent the unitary matrix Q as a product of elementary reflectors (peep Further Details for the receipts).


πŸ¦‹ LDA πŸ¦‹

LDA is INTEGER β€” the leading dimension of the array A. and the vibe check is: LDA >= max(1,M). no cap, it's non-negotiable πŸ™ˆ


πŸŽ€ TAUA πŸŽ€

TAUA is COMPLEX*16 array, dimension (min(M,N)).

these are the scalar factors of the elementary reflectors that represent the unitary matrix Q (again, Further Details has the lore).


🌸 B 🌸

B is COMPLEX*16 array, dimension (LDB,N).

On entry, it's the P-by-N matrix B.

On exit, the elements on and above the diagonal of the array hold the min(P,N)-by-N upper trapezoidal matrix T (and T is upper triangular if P >= N). the elements below the diagonal, chillin' with the array TAUB, represent the unitary matrix Z as a product of elementary reflectors (Further Details, bestie, Further Details).


⭐ LDB ⭐

LDB is INTEGER β€” the leading dimension of the array B, and it must satisfy LDB >= max(1,P). rules are rules πŸ’…


🧚 TAUB 🧚

TAUB is COMPLEX*16 array, dimension (min(P,N)).

the scalar factors of the elementary reflectors which represent the unitary matrix Z (Further Details!! it's iconique).


πŸ”₯ WORK πŸ”₯

WORK is COMPLEX*16 array, dimension (MAX(1,LWORK)).

On exit, if INFO = 0, then WORK(1) returns the optimal LWORK. yes, it reports back. main character behavior.


πŸ‘‘ LWORK πŸ‘‘

LWORK is INTEGER β€” the dimension of the array WORK.

the bare minimum is LWORK >= max(1,N,M,P).

but for optimum performance, 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
  • NB3 is the optimal blocksize for a call of ZUNMRQ
⚠️ and 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, don't go expecting a complaint, it's literally built different.

πŸ’œ INFO πŸ’œ

INFO is INTEGER, your little status report:

  • = 0: successful exit πŸŽ‰ slay
  • < 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.

the whole squad really said "we made this" and honestly? respect 🫢


✨ Further Details ✨

okay this is the part where it gets GOOD, strap in πŸŽ€

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 πŸ’–

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 πŸ’–

and one last lil footnote for the completionists: this is defined at line 212 of file zggrqf.f, and this whole author bit was generated automatically by Doxygen for LAPACK from the source code 🌸


okay that's the whole page bestie, you're officially a zggrqf girlie now πŸ’… this was LAPACK, Version 3.12.0 β€” the ggrqf(3) girlies stay winning, and yes the date lives in that footer too, go check the source code if you need the exact timestamp πŸŽ€ mwah, study hard, hydrate, and may all your arguments be legal ✨

πŸ“¦ where this page comes from