SRC/dlaqp2rk.f(3)

📦
version 3.12.1 · 2 versions
, in arch rolling

🫶 NAME 🫶

SRC/dlaqp2rk.f(3) — straight out of the Library Functions Manual, bestie. This is the page for SRC/dlaqp2rk.f.

✨ SYNOPSIS ✨

🌟 Functions/Subroutines

  • subroutine dlaqp2rk (m, n, nrhs, ioffset, kmax, abstol, reltol, kp1, maxc2nrm, a, lda, k, maxc2nrmk, relmaxc2nrmk, jpiv, tau, vn1, vn2, work, info) — DLAQP2RK computes truncated QR factorization with column pivoting of a real matrix block using Level 2 BLAS and overwrites a real m-by-nrhs matrix B with Q**T * B.
subroutine dlaqp2rk (m, n, nrhs, ioffset, kmax, abstol, reltol, kp1,
    maxc2nrm, a, lda, k, maxc2nrmk, relmaxc2nrmk, jpiv, tau, vn1, vn2,
    work, info)

💖 Function/Subroutine Documentation 💖

subroutine dlaqp2rk (integer m, integer n, integer nrhs, integer ioffset,
    integer kmax, double precision abstol, double precision reltol, integer
    kp1, double precision maxc2nrm, double precision, dimension( lda, * ) a,
    integer lda, integer k, double precision maxc2nrmk, double precision
    relmaxc2nrmk, integer, dimension( * ) jpiv, double precision, dimension(
    * ) tau, double precision, dimension( * ) vn1, double precision,
    dimension( * ) vn2, double precision, dimension( * ) work, integer info)

DLAQP2RK computes truncated QR factorization with column pivoting of a real matrix block using Level 2 BLAS and overwrites a real m-by-nrhs matrix B with Q**T * B.

🎯 Purpose

Okay so here’s the whole vibe: DLAQP2RK computes a truncated (rank K) or full rank Householder QR factorization with column pivoting of a real matrix block A(IOFFSET+1:M,1:N) as

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

It uses Level 2 BLAS. The block A(1:IOFFSET,1:N) is accordingly pivoted, but not factorized. Not me forgetting that part — that’s literally the deal, bestie.

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

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

🌀 KMAX

KMAX is INTEGER.

This is 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. Iconic little limit, honestly.

  • a) If KMAX >= min(M-IOFFSET,N), then this stopping criterion is not used, and 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 the factorization is not performed, and the matrices A and B and the arrays TAU, IPIV are not modified.
Not gonna lie, that IPIV spelling is exactly what the original says, so I’m keeping it. No cap.

🌀 ABSTOL

ABSTOL is DOUBLE PRECISION, and it cannot be NaN.

This is the second factorization stopping criterion.

It’s 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, and the routine factorizes columns depending on KMAX 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, and it cannot be NaN.

This is the third factorization stopping criterion.

It’s 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, and the routine factorizes columns depending on KMAX 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 that last one “d)” — I’m not fixing it, bestie. We preserve the lore.

🌀 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_mat.

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

  1. The elements in block A(IOFFSET+1:M,1:K) below the diagonal together with the array TAU represent the orthogonal matrix Q(K) as a product of elementary reflectors.
  2. The upper triangular block of the matrix A stored in A(IOFFSET+1:M,1:K) is the triangular factor obtained.
  3. The block of the matrix A stored in A(1:IOFFSET,1:N) has been accordingly pivoted, but not factorized.
  4. The rest of the array A, block A(IOFFSET+1:M,K+1:N+NRHS). The left part A(IOFFSET+1:M,K+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(K)**T.

🌀 LDA

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

🌀 K

K 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 <= K <= min(M-IOFFSET,KMAX,N).

K 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 K. 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 K) to the maximum column 2-norm of the whole original matrix A. 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.

🌀 WORK

WORK is DOUBLE PRECISION array, dimension (N-1). Used in DLARF1F subroutine to apply an elementary reflector from the left.

🌀 INFO

INFO is INTEGER.

  1. INFO = 0: successful exit.
  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 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.
  1. 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

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

📚 References

Okay bestie, the receipts are right here — no cap:

  • [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.
The source’s contributor block is literally giving “Berkeley besties wrote this in November 2023” energy. 🧚✨

Definition at line 340 of file dlaqp2rk.f.

👑 Author

Generated automatically by Doxygen for LAPACK from the source code.

💖 That’s the whole page, bestie — LAPACK Version 3.12.0, source SRC/dlaqp2rk.f(3), and yes, she ate. 💅🎀✨

📦 where this page comes from