SRC/dlaqp3rk.f(3)

📦

version 3.12.1 · 3 versions

3.12.1 · arch rolling (latest)
3.12.0 · opensuse-leap 16.0
3.12.0 · centos-stream 10, fedora 43, fedora 44

🎀 SRC/dlaqp3rk.f 🎀

okay so this is the Library Functions Manual page for SRC/dlaqp3rk.f(3), and bestie, it's giving Fortran library-function main character energy. Part 1 starts now, no cap. 💖

🌸 NAME 🌸

SRC/dlaqp3rk.f

✨ SYNOPSIS ✨

🌈 Functions/Subroutines 🌈

subroutine dlaqp3rk (...) — bestie, this one computes a step of truncated QR factorization with column pivoting of a real m-by-n matrix A using Level 3 BLAS, and it overwrites a real m-by-nrhs matrix B with Q**T * B. Slay.

subroutine dlaqp3rk (m, n, nrhs, ioffset, nb, abstol, reltol, kp1,
    maxc2nrm, a, lda, done, kb, maxc2nrmk, relmaxc2nrmk, jpiv, tau, vn1,
    vn2, auxv, f, ldf, iwork, info)

💅 Function/Subroutine Documentation 💅

subroutine dlaqp3rk (integer m, integer n, integer nrhs, integer ioffset,
    integer nb, double precision abstol, double precision reltol, integer
    kp1, double precision maxc2nrm, double precision, dimension( lda, * ) a,
    integer lda, logical done, integer kb, double precision maxc2nrmk,
    double precision relmaxc2nrmk, integer, dimension( * ) jpiv, double
    precision, dimension( * ) tau, double precision, dimension( * ) vn1,
    double precision, dimension( * ) vn2, double precision, dimension( * )
    auxv, double precision, dimension( ldf, * ) f, integer ldf, integer,
    dimension( * ) iwork, integer info)

DLAQP3RK computes a step of truncated QR factorization with column pivoting of a real m-by-n matrix A using Level 3 BLAS, and it overwrites a real m-by-nrhs matrix B with Q**T * B. That's the whole vibe, and honestly? Iconic. 💫

🎀 Purpose 🎀

okay so DLAQP3RK computes a step of truncated QR factorization with column pivoting of a real M-by-N matrix A block A(IOFFSET+1:M,1:N) by using Level 3 BLAS as

A * P(KB) = Q(KB) * R(KB).

The routine tries to factorize NB columns from A starting from the row IOFFSET+1 and updates the residual matrix with BLAS 3 xGEMM. The number of actually factorized columns is returned, and bestie, it can be smaller than NB. 🙈

Block A(1:IOFFSET,1:N) is accordingly pivoted, but not factorized. No cap.

The routine also overwrites the right-hand-sides B matrix stored in A(IOFFSET+1:M,1:N+1:N+NRHS) with Q(KB)**T * B. Periodt.

Cases when the number of factorized columns KB < NB:

Case (1) — in some cases, due to catastrophic cancellations, it cannot factorize all NB columns and needs to update the residual matrix. Hence, the actual number of factorized columns in the block returned in KB is smaller than NB. The logical DONE is returned as FALSE. The factorization of the whole original matrix A_orig must proceed with the next block. 😭
Case (2) — whenever the stopping criterion ABSTOL or RELTOL is satisfied, the factorization of the whole original matrix A_orig is stopped, and the logical DONE is returned as TRUE. The number of factorized columns, which is smaller than NB, is returned in KB. 💖
Case (3) — in case both stopping criteria ABSTOL or RELTOL are not used, and when the residual matrix is a zero matrix in some factorization step KB, the factorization of the whole original matrix A_orig is stopped, and the logical DONE is returned as TRUE. The number of factorized columns, which is smaller than NB, is returned in KB. ✨
Case (4) — whenever NaN is detected in the matrix A or in the array TAU, the factorization of the whole original matrix A_orig is stopped, and the logical DONE is returned as TRUE. The number of factorized columns, which is smaller than NB, is returned in KB. The INFO parameter is set to the column index of the first NaN occurrence. 🫶

🦋 Parameters 🦋

M

M is INTEGER. 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. 🎀

IOFFSET

IOFFSET is INTEGER. The number of rows of the matrix A that must be pivoted but not factorized. IOFFSET >= 0.

IOFFSET also represents the number of columns of the whole original matrix A_orig that have been factorized in the previous steps. iykyk. 🧚

NB

NB is INTEGER. Factorization block size, i.e the number of columns to factorize in the matrix A. 0 <= NB.

If NB = 0, then the routine exits immediately. This means that the factorization is not performed, the matrices A and B and the arrays TAU, IPIV are not modified. yes bestie, it says IPIV right there — keep it moving. 💀

ABSTOL

ABSTOL is DOUBLE PRECISION, cannot be NaN.

The absolute tolerance (stopping threshold) for maximum column 2-norm of the residual matrix. The algorithm converges (stops the factorization) when the maximum column 2-norm of the residual matrix is less than or equal to ABSTOL.

a) If ABSTOL < 0.0, then this stopping criterion is not used, the routine factorizes columns depending on NB and RELTOL. This includes the case ABSTOL = -Inf. 🌈
b) If 0.0 <= ABSTOL then the input value of ABSTOL is used. ⭐

RELTOL

RELTOL is DOUBLE PRECISION, cannot be NaN.

The tolerance (stopping threshold) for the ratio of the maximum column 2-norm of the residual matrix to the maximum column 2-norm of the original matrix A_orig. The algorithm converges (stops the factorization), when this ratio is less than or equal to RELTOL.

a) If RELTOL < 0.0, then this stopping criterion is not used, the routine factorizes columns depending on NB and ABSTOL. This includes the case RELTOL = -Inf. 🌸
d) If 0.0 <= RELTOL then the input value of RELTOL is used. yes, the original labels this one d) — not me fixing it, bestie. 💅

KP1

KP1 is INTEGER. The index of the column with the maximum 2-norm in the whole original matrix A_orig determined in the main routine DGEQP3RK. 1 <= KP1 <= N_orig. 👑

MAXC2NRM

MAXC2NRM is DOUBLE PRECISION. The maximum column 2-norm of the whole original matrix A_orig computed in the main routine DGEQP3RK. MAXC2NRM >= 0. 🔥

A

A is DOUBLE PRECISION array, dimension (LDA,N+NRHS).

On entry: the M-by-N matrix A and M-by-NRHS matrix B, as in

                                N     NRHS
array_A   =   M  [ mat_A, mat_B ]

On exit:

The elements in block A(IOFFSET+1:M,1:KB) below the diagonal together with the array TAU represent the orthogonal matrix Q(KB) as a product of elementary reflectors. ✨
The upper triangular block of the matrix A stored in A(IOFFSET+1:M,1:KB) is the triangular factor obtained. 💖
The block of the matrix A stored in A(1:IOFFSET,1:N) has been accordingly pivoted, but not factorized. 🫶
The rest of the array A, block A(IOFFSET+1:M,KB+1:N+NRHS). The left part A(IOFFSET+1:M,KB+1:N) of this block contains the residual of the matrix A, and, if NRHS > 0, the right part of the block A(IOFFSET+1:M,N+1:N+NRHS) contains the block of the right-hand-side matrix B. Both these blocks have been updated by multiplication from the left by Q(KB)**T. no cap, that's the whole tea. 🍓

LDA

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

DONE

DONE is LOGICAL.

TRUE: a) if the factorization completed before processing all min(M-IOFFSET,NB,N) columns due to ABSTOL or RELTOL criterion, b) if the factorization completed before processing all min(M-IOFFSET,NB,N) columns due to the residual matrix being a ZERO matrix. c) when NaN was detected in the matrix A or in the array TAU. 🔥
FALSE: otherwise. 🙈

KB

KB is INTEGER. 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. 0 <= KB <= min(M-IOFFSET,NB,N).

KB also represents the number of non-zero Householder vectors. 👑

MAXC2NRMK

MAXC2NRMK is DOUBLE PRECISION. The maximum column 2-norm of the residual matrix, when the factorization stopped at rank KB. MAXC2NRMK >= 0. ⭐

RELMAXC2NRMK

RELMAXC2NRMK is DOUBLE PRECISION. The ratio MAXC2NRMK / MAXC2NRM of the maximum column 2-norm of the residual matrix (when the factorization stopped at rank KB) to the maximum column 2-norm of the original matrix A_orig. RELMAXC2NRMK >= 0. 🌈

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). 💅

TAU

TAU is DOUBLE PRECISION array, dimension (min(M-IOFFSET,N)). The scalar factors of the elementary reflectors. 🎀

VN1

VN1 is DOUBLE PRECISION array, dimension (N). The vector with the partial column norms. 🌸

VN2

VN2 is DOUBLE PRECISION array, dimension (N). The vector with the exact column norms. 🦋

AUXV

AUXV is DOUBLE PRECISION array, dimension (NB). Auxiliary vector. 🧚

F

F's full description is literally the next part, bestie — this page cuts off right here. Hold that thought. 💜

F — a DOUBLE PRECISION array, dimension (LDF,NB). It’s giving the matrix F**T = L*(Y**T)*A, no cap. 💅
LDF — INTEGER, the leading dimension of array F. It has to satisfy LDF >= max(1,N+NRHS) — respect the boundary, bestie. ✨
IWORK — INTEGER array, dimension (N-1). It’s a work array. ( IWORK is used to store indices of columns for norm downdating in the residual matrix. ) 🫶
INFO — INTEGER. The receipts are:
1. INFO = 0: successful exit. Slay. ✨
2. 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 KB+1 ( when KB columns have been factorized ). 💀 On exit:
  - KB is set to the number of factorized columns without exception.
  - MAXC2NRMK is set to NaN.
  - RELMAXC2NRMK is set to NaN.
  - TAU(KB+1:min(M,N)) is not set and contains undefined elements. If j_1=KB+1, TAU(KB+1) may contain NaN.
3. 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 actorization step KB+1 ( when KB columns have been factorized ). 🔥

👑 Author

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

📚 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 398 of file dlaqp3rk.f. 🧚

🤖 Author

Generated automatically by Doxygen for LAPACK from the source code.

LAPACK Version 3.12.0 · SRC/dlaqp3rk.f(3) — the source/version tea, dated by the Doxygen footer. Mwah, bestie 💋💖

📦 where this page comes from

arch rolling: lapack-doc 3.12.1-2 · custom
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms