ZGEQP3RK(3)

💅 `zgeqp3rk.f(3)` 💅

okay bestie, this is the zgeqp3rk.f(3) page from the Library Functions Manual, and it is literally all about the ZGEQP3RK subroutine. buckle up, because this one is doing two jobs at once and it is lowkey iconic. 💖

✨ NAME ✨

the main character file is:

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

🦋 SYNOPSIS 🦋

🧚 Functions/Subroutines 🧚

subroutine ZGEQP3RK (m, n, nrhs, kmax, abstol, reltol, a, lda, k,
    maxc2nrmk, relmaxc2nrmk, jpiv, tau, work, lwork, rwork, iwork, info)

ZGEQP3RK computes a truncated Householder QR factorization with column pivoting of a complex m-by-n matrix A by using Level 3 BLAS, and it overwrites the m-by-nrhs matrix B with Q**H * B. periodt. 💅

🌸 Function/Subroutine Documentation 🌸

subroutine ZGEQP3RK (integer m, integer n, integer nrhs, integer kmax,
    double precision abstol, double precision reltol, complex*16, dimension(
    lda, * ) a, integer lda, integer k, double precision maxc2nrmk, double
    precision relmaxc2nrmk, integer, dimension( * ) jpiv, complex*16,
    dimension( * ) tau, complex*16, dimension( * ) work, integer lwork,
    double precision, dimension( * ) rwork, integer, dimension( * ) iwork,
    integer info)

ZGEQP3RK computes a truncated Householder QR factorization with column pivoting of a complex m-by-n matrix A using Level 3 BLAS, and then overwrites the m-by-nrhs matrix B with Q**H * B. it's giving “two tasks, one subroutine, no wasted motion.” ✨

🎀 Purpose 🎀

okay so ZGEQP3RK performs two tasks simultaneously:

Task 1: The routine computes a truncated (rank K) or full rank Householder QR factorization with column pivoting of a complex M-by-N matrix A using Level 3 BLAS. K is the number of columns that were factorized, i.e. factorization rank of the factor R, K <= min(M,N).

A * P(K) = Q(K) * R(K)  =

       = Q(K) * ( R11(K) R12(K) ) = Q(K) * (   R(K)_approx    )
                ( 0      R22(K) )          ( 0  R(K)_residual ),

where:

P(K) is an N-by-N permutation matrix;
Q(K) is an M-by-M unitary matrix;
R(K)_approx = ( R11(K), R12(K) ) is a rank K approximation of the full rank factor R with K-by-K upper-triangular R11(K) and K-by-N rectangular R12(K). The diagonal entries of R11(K) appear in non-increasing order of absolute value, and absolute values of all of them exceed the maximum column 2-norm of R22(K) up to roundoff error.
R(K)_residual = R22(K) is the residual of a rank K approximation of the full rank factor R. It is an (M-K)-by-(N-K) rectangular matrix;
0 is an (M-K)-by-K zero matrix.

Task 2: At the same time, the routine overwrites a complex M-by-NRHS matrix B with Q(K)**H * B using Level 3 BLAS. 🫶

=====================================================================

The matrices A and B are stored on input in the array A as the left and right blocks A(1:M,1:N) and A(1:M, N+1:N+NRHS) respectively.

                                 N     NRHS
            array_A   =   M  [ mat_A, mat_B ]

The truncation criteria (i.e. when to stop the factorization) can be any of the following:

The input parameter KMAX, the maximum number of columns KMAX to factorize, i.e. the factorization rank is limited to KMAX. If KMAX >= min(M,N), the criterion is not used.
The input parameter ABSTOL, the absolute tolerance for the maximum column 2-norm of the residual matrix R22(K). This means that the factorization stops if this norm is less or equal to ABSTOL. If ABSTOL < 0.0, the criterion is not used.
The input parameter RELTOL, the tolerance for the maximum column 2-norm matrix of the residual matrix R22(K) divided by the maximum column 2-norm of the original matrix A, which is equal to abs(R(1,1)). This means that the factorization stops when the ratio of the maximum column 2-norm of R22(K) to the maximum column 2-norm of A is less than or equal to RELTOL. If RELTOL < 0.0, the criterion is not used.
In case both stopping criteria ABSTOL or RELTOL are not used, and when the residual matrix R22(K) is a zero matrix in some factorization step K. ( This stopping criterion is implicit. )

The algorithm stops when any of these conditions is first satisfied, otherwise the whole matrix A is factorized. no cap. 🔥

To factorize the whole matrix A, use the values KMAX >= min(M,N), ABSTOL < 0.0 and RELTOL < 0.0.

The routine returns:

a) Q(K), R(K)_approx = ( R11(K), R12(K) ), R(K)_residual = R22(K), P(K), i.e. the resulting matrices of the factorization; P(K) is represented by JPIV, ( if K = min(M,N), R(K)_approx is the full factor R, and there is no residual matrix R(K)_residual);
b) K, the number of columns that were factorized, i.e. factorization rank;
c) MAXC2NRMK, the maximum column 2-norm of the residual matrix R(K)_residual = R22(K), ( if K = min(M,N), MAXC2NRMK = 0.0 );
d) RELMAXC2NRMK equals MAXC2NRMK divided by MAXC2NRM, the maximum column 2-norm of the original matrix A, which is equal to abs(R(1,1)), ( if K = min(M,N), RELMAXC2NRMK = 0.0 );
e) Q(K)**H * B, the matrix B with the unitary transformation Q(K)**H applied on the left.

The N-by-N permutation matrix P(K) is stored in a compact form in the integer array JPIV. For 1 <= j <= N, column j of the matrix A was interchanged with column JPIV(j). 🧚

The M-by-M unitary matrix Q is represented as a product of elementary Householder reflectors

Q(K) = H(1) *  H(2) * . . . * H(K),

where K is the number of columns that were factorized.

Each H(j) has the form

H(j) = I - tau * v * v**H,

where 1 <= j <= K and

I is an M-by-M identity matrix,
tau is a complex scalar,
v is a complex vector with v(1:j-1) = 0 and v(j) = 1.

v(j+1:M) is stored on exit in A(j+1:M,j) and tau in TAU(j). 💜

See the Further Details section for more information.

🌈 Parameters 🌈

M

M is INTEGER. it's the number of rows of the matrix A. M >= 0. 💖

N

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

NRHS

NRHS is INTEGER. the number of right hand sides, i.e. the number of columns of the matrix B. NRHS >= 0. 🎀

KMAX

KMAX is INTEGER.

it's the first factorization stopping criterion. KMAX >= 0.

it's the maximum number of columns of the matrix A to factorize, i.e. the maximum factorization rank.

a) If KMAX >= min(M,N), then this stopping criterion is not used, the routine factorizes columns depending on ABSTOL and RELTOL.
b) If KMAX = 0, then this stopping criterion is satisfied on input and the routine exits immediately. This means that the factorization is not performed, the matrices A and B are not modified, and the matrix A is itself the residual. 🙈

ABSTOL

ABSTOL is DOUBLE PRECISION.

it's the second factorization stopping criterion, cannot be NaN.

it's the absolute tolerance (stopping threshold) for maximum column 2-norm of the residual matrix R22(K). The algorithm converges (stops the factorization) when the maximum column 2-norm of the residual matrix R22(K) is less than or equal to ABSTOL. Let SAFMIN = DLAMCH('S').

a) If ABSTOL is NaN, then no computation is performed and an error message ( INFO = -5 ) is issued by XERBLA.
b) If ABSTOL < 0.0, then this stopping criterion is not used, the routine factorizes columns depending on KMAX and RELTOL. This includes the case ABSTOL = -Inf.
c) If 0.0 <= ABSTOL < 2*SAFMIN, then ABSTOL = 2*SAFMIN is used. This includes the case ABSTOL = -0.0.
d) If 2*SAFMIN <= ABSTOL then the input value of ABSTOL is used.

Let MAXC2NRM be the maximum column 2-norm of the whole original matrix A. If ABSTOL chosen above is >= MAXC2NRM, then this stopping criterion is satisfied on input and routine exits immediately after MAXC2NRM is computed. The routine returns MAXC2NRM in MAXC2NORMK, and 1.0 in RELMAXC2NORMK. This includes the case ABSTOL = +Inf. This means that the factorization is not performed, the matrices A and B are not modified, and the matrix A is itself the residual. 💀

RELTOL

Okay so this is the third stopping criterion, and the one rule is: it cannot be NaN. Periodt. 🫶

It's the tolerance (read: stopping threshold) for the ratio

abs(R(K+1,K+1))/abs(R(1,1))

which is the maximum column 2-norm of the residual matrix R22(K) over the maximum column 2-norm of the original matrix A. The algorithm converges — like, actually stops factorizing — when abs(R(K+1,K+1))/abs(R(1,1)) is less than or equal to RELTOL. And let EPS = DLAMCH('E') 💅

a) If RELTOL is NaN, then literally no computation is performed and an error message (INFO = -6) is issued by XERBLA. bestie. it just gives up 😭
b) If RELTOL < 0.0, then this stopping criterion is simply not used, and the routine factorizes columns depending on KMAX and ABSTOL. This includes the case RELTOL = -Inf.
c) If 0.0 <= RELTOL < EPS, then RELTOL = EPS is used. This includes the case RELTOL = -0.0.
d) If EPS <= RELTOL then the input value of RELTOL is used, no notes.

Now, let MAXC2NRM be the maximum column 2-norm of the whole original matrix A. If the RELTOL you chose above is >= 1.0, then this stopping criterion is already satisfied on input and the routine exits immediately after MAXC2NRM is computed. The routine returns MAXC2NRM in MAXC2NORMK, and 1.0 in RELMAXC2NORMK. This includes the case RELTOL = +Inf. Which means: the factorization is not performed, the matrices A and B are not modified, and the matrix A is itself the residual. iconic behaviour honestly ✨

NOTE: we recommend that RELTOL satisfy min( 10*max(M,N)*EPS, sqrt(EPS) ) <= RELTOL

`A`</p> 💖

A is COMPLEX*16 array, dimension (LDA,N+NRHS).

On entry (what you hand it):

a) The subarray A(1:M,1:N) contains the M-by-N matrix A.
b) The subarray A(1:M,N+1:N+NRHS) contains the M-by-NRHS matrix B.

                                 N     NRHS
    array_A   =   M  [ mat_A, mat_B ]

On exit (what you get back, and it's a whole glow-up 🌈):

a) The subarray A(1:M,1:N) contains parts of the factors of the matrix A:
1. If K = 0, A(1:M,1:N) contains the original matrix A.
2. If K > 0, A(1:M,1:N) contains parts of the factors:
  1. The elements below the diagonal of the subarray A(1:M,1:K) together with TAU(1:K) represent the unitary matrix Q(K) as a product of K Householder elementary reflectors.
  2. The elements on and above the diagonal of the subarray A(1:K,1:N) contain K-by-N upper-trapezoidal matrix R(K)_approx = ( R11(K), R12(K) ).

NOTE: If K=min(M,N), i.e. full rank factorization, then R_approx(K) is the full factor R which is upper-trapezoidal. If, in addition, M>=N, then R is upper-triangular. slay 💅

The subarray A(K+1:M,K+1:N) contains (M-K)-by-(N-K) rectangular matrix R(K)_residual = R22(K).

b) If NRHS > 0, the subarray A(1:M,N+1:N+NRHS) contains the M-by-NRHS product Q(K)**H * B.

`LDA` 🦋

LDA is INTEGER.

The leading dimension of the array A. Requirement: LDA >= max(1,M). This is the leading dimension for both matrices, A and B. one value, two matrices, efficiency 💅

`K` ⭐

K is INTEGER.

The factorization rank of the matrix A, i.e. the rank of the factor R, which is the same as the number of non-zero rows of the factor R. Bounds, memorise them: 0 <= K <= min(M,KMAX,N).

K also represents the number of non-zero Householder vectors. two jobs, main character energy 👑

NOTE: If K = 0, then - a) the arrays A and B are not modified; - b) the array TAU(1:min(M,N)) is set to ZERO, if the matrix A does not contain NaN, otherwise the elements TAU(1:min(M,N)) are undefined (💀 careful); - c) the elements of the array JPIV are set as follows: for j = 1:N, JPIV(j) = j.

`MAXC2NRMK` 🌸

MAXC2NRMK is DOUBLE PRECISION.

The maximum column 2-norm of the residual matrix R22(K), when the factorization stopped at rank K. Guaranteed MAXC2NRMK >= 0.

a) If K = 0, i.e. the factorization was not performed, the matrix A was not modified and is itself a residual matrix, then MAXC2NRMK equals the maximum column 2-norm of the original matrix A.
b) If 0 < K < min(M,N), then MAXC2NRMK is returned.
c) If K = min(M,N), i.e. the whole matrix A was factorized and there is no residual matrix, then MAXC2NRMK = 0.0. nothing left, zero, queen of leaving no crumbs ✨

NOTE: MAXC2NRMK in the factorization step K would equal R(K+1,K+1) in the next factorization step K+1. iykyk 🔥

`RELMAXC2NRMK` 💜

RELMAXC2NRMK is DOUBLE PRECISION.

The ratio MAXC2NRMK / MAXC2NRM — that's the maximum column 2-norm of the residual matrix R22(K) (when the factorization stopped at rank K) over the maximum column 2-norm of the whole original matrix A. Guaranteed RELMAXC2NRMK >= 0.

a) If K = 0, i.e. the factorization was not performed, the matrix A was not modified and is itself a residual matrix, then RELMAXC2NRMK = 1.0.
b) If 0 < K < min(M,N), then RELMAXC2NRMK = MAXC2NRMK / MAXC2NRM is returned.
c) If K = min(M,N), i.e. the whole matrix A was factorized and there is no residual matrix, then RELMAXC2NRMK = 0.0.

NOTE: RELMAXC2NRMK in the factorization step K would equal abs(R(K+1,K+1))/abs(R(1,1)) in the next factorization step K+1. 🧚

`JPIV` 🍓

JPIV is INTEGER array, dimension (N).

Column pivot indices. For 1 <= j <= N, column j of the matrix A was interchanged with column JPIV(j).

The elements of the array JPIV(1:N) are always set by the routine — like, even when no columns were factorized, i.e. when K = 0, the elements are set as JPIV(j) = j for j = 1:N. reliable. consistent. we stan 🫶

`TAU` 🎀

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

The scalar factors of the elementary reflectors.

If 0 < K <= min(M,N), only the elements TAU(1:K) of the array TAU are modified by the factorization. After the factorization is computed, if no NaN was found during the factorization, the remaining elements TAU(K+1:min(M,N)) are set to zero — otherwise the elements TAU(K+1:min(M,N)) are not set and therefore undefined. (If K = 0, all elements of TAU are set to zero, if the matrix A does not contain NaN.) 🙈

`WORK` 🦋

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

On exit, if INFO = 0, WORK(1) returns the optimal LWORK. look at her, reporting back 💅

`LWORK` ⭐

LWORK is INTEGER.

The dimension of the array WORK.

Requirement: LWORK >= N+NRHS-1

For optimal performance, LWORK >= NB*( N+NRHS+1 ), where NB is the optimal block size for ZGEQP3RK returned by ILAENV. Minimal block size MINNB=2.

NOTE: the decision whether to use unblocked BLAS 2 or blocked BLAS 3 code is based not only on the dimension LWORK of the available workspace WORK, but also on the matrix A dimension N via the crossover point NX returned by ILAENV. (For N less than NX, unblocked code should be used.) 💀

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. no scolding, just vibes 🌸

`RWORK` 🌈

RWORK is DOUBLE PRECISION array, dimension (2*N).

`IWORK` 🧚

IWORK is INTEGER array, dimension (N-1).

Is a work array. (IWORK is used to store indices of columns for norm downdating in the residual matrix in the blocked step auxiliary subroutine ZLAQP3RK.) iykyk 🔥

`INFO`

INFO is an INTEGER, and it's giving full exit-status realness — here's the whole tea, no cap:

INFO = 0 — successful exit. We love to see it 💖
INFO < 0 — if INFO = -i, the i-th argument had an illegal value. Rude but noted 🙈
If INFO = j_1, where 1 <= j_1 <= N, then NaN was detected and the routine stops the computation. The j_1-th column of the matrix A or the j_1-th element of array TAU contains the first occurrence of NaN in the factorization step K+1 ( when K columns have been factorized ).

On exit:

K is set to the number of factorized columns without exception.
MAXC2NRMK is set to NaN.
RELMAXC2NRMK is set to NaN.
TAU(K+1:min(M,N)) is not set and contains undefined elements. If j_1=K+1, TAU(K+1) may contain NaN.

If INFO = j_2, where N+1 <= j_2 <= 2*N, then no NaN was detected, but +Inf (or -Inf) was detected and the routine continues the computation until completion. The (j_2-N)-th column of the matrix A contains the first occurrence of +Inf (or -Inf) in the factorization step K+1 ( when K columns have been factorized ).

👑 AUTHOR 👑

The icons behind this masterpiece:

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

🔥 FURTHER DETAILS 🔥

Okay so ZGEQP3RK is based on the same BLAS3 Householder QR factorization algorithm with column pivoting as in the ZGEQP3 routine, which uses the ZLARFG routine to generate Householder reflectors for QR factorization. We can also write:

A = A_approx(K) + A_residual(K)

The low rank approximation matrix A(K)_approx from the truncated QR factorization of rank K of the matrix A is:

   A(K)_approx = Q(K) * ( R(K)_approx ) * P(K)**T
                        (     0     0 )

               = Q(K) * ( R11(K) R12(K) ) * P(K)**T
                        (      0      0 )

The residual A_residual(K) of the matrix A is:

   A_residual(K) = Q(K) * ( 0              0 ) * P(K)**T =
                          ( 0  R(K)_residual )

                 = Q(K) * ( 0        0 ) * P(K)**T
                          ( 0   R22(K) )

The truncated (rank K) factorization guarantees that the maximum column 2-norm of A_residual(K) is less than or equal to MAXC2NRMK up to roundoff error.

NOTE: An approximation of the null vectors of A can be easily computed from R11(K) and R12(K):

       Null( A(K) )_approx = P * ( inv(R11(K)) * R12(K) )
                                 (         -I           )

📚 REFERENCES 📚

[1] A Level 3 BLAS QR factorization algorithm with column pivoting developed in 1996. G. Quintana-Orti, Depto. de Informatica, Universidad Jaime I, Spain. X. Sun, Computer Science Dept., Duke University, USA. C. H. Bischof, Math. and Comp. Sci. Div., Argonne National Lab, USA. A BLAS-3 version of the QR factorization with column pivoting. LAPACK Working Note 114 and in SIAM J. Sci. Comput., 19(5):1486-1494, Sept. 1998.
[2] A partial column norm updating strategy developed in 2006. Z. Drmac and Z. Bujanovic, Dept. of Math., University of Zagreb, Croatia. On the failure of rank revealing QR factorization software – a case study. LAPACK Working Note 176. and in ACM Trans. Math. Softw. 35, 2, Article 12 (July 2008), 28 pages.

🌈 CONTRIBUTORS 🌈

November 2023, Igor Kozachenko, James Demmel, EECS Department, University of California, Berkeley, USA.

Definition at line 588 of file zgeqp3rk.f.

🎀 AUTHOR (AUTOGENERATED) 🎀

Generated automatically by Doxygen for LAPACK from the source code.

That's the whole vibe, bestie — this page came from LAPACK Version 3.12.0, source file /home/abui.../zgeqp3rk.f(3). Go off and factorize something iconic 💅✨

📦 where this page comes from

opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms