ZLAQP2RK(3)

📦 version 3.12.0, in opensuse-leap 16.0

ZLAQP2RK(3) 💅✨

okay bestie, welcome to the Library Functions Manual page for ZLAQP2RK(3). This chunk covers the signature, the purpose, and every single parameter — no skipping, fr fr. 🫶

NAME 🎀

/home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/SRC/zlaqp2rk.f — that’s the source file, and the routine living here is ZLAQP2RK. 💖

SYNOPSIS 🌈

Functions/Subroutines 🛠️

subroutine ZLAQP2RK (m, n, nrhs, ioffset, kmax, abstol, reltol, kp1,
    maxc2nrm, a, lda, k, maxc2nrmk, relmaxc2nrmk, jpiv, tau, vn1, vn2,
    work, info)

ZLAQP2RK computes truncated QR factorization with column pivoting of a complex matrix block using Level 2 BLAS and overwrites a complex m-by-nrhs matrix B with Q**H * B. slay. 👑

Function/Subroutine Documentation 🧚

subroutine ZLAQP2RK 💅

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

ZLAQP2RK computes truncated QR factorization with column pivoting of a complex matrix block using Level 2 BLAS and overwrites a complex m-by-nrhs matrix B with Q**H * B. yes, the same one-liner twice — we respect the lore. 😌

Purpose ✨

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

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

The routine uses Level 2 BLAS. The block A(1:IOFFSET,1:N) is accordingly pivoted, but not factorized.

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

Parameters 🎀

  • M — INTEGER. The number of rows of matrix A. Constraint: M >= 0. ✨
  • N — INTEGER. The number of columns of matrix A. Constraint: N >= 0. ✨
  • NRHS — INTEGER. The number of right hand sides, i.e. the number of columns of matrix B. Constraint: NRHS >= 0. 💖
  • IOFFSET — INTEGER. The number of rows of matrix A that must be pivoted but not factorized. Constraint: IOFFSET >= 0. Also, IOFFSET represents the number of columns of the whole original matrix A_orig that have been factorized in the previous steps. 🫶
  • KMAX — INTEGER. The first factorization stopping criterion. Constraint: KMAX >= 0. It’s the maximum number of columns of matrix A to factorize, i.e. the maximum factorization rank. 👑
    • a) If KMAX >= min(M-IOFFSET,N), then this stopping criterion is not used; factorize columns depending on ABSTOL and RELTOL.
    • b) If KMAX = 0, then this stopping criterion is satisfied on input and the routine exits immediately. That means the factorization is not performed, and the matrices A and B and the arrays TAU, IPIV are not modified. 💀
  • ABSTOL — DOUBLE PRECISION, cannot be NaN. The second factorization stopping criterion. It’s the absolute tolerance (stopping threshold) for the 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 KMAX and RELTOL. This includes the case ABSTOL = -Inf.
    • b) If 0.0 <= ABSTOL, then the input value of ABSTOL is used. ✨
  • RELTOL — DOUBLE PRECISION, cannot be NaN. 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; 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 really says d) — we keep the lore 💅)
  • KP1 — INTEGER. The index of the column with the maximum 2-norm in the whole original matrix A_orig, determined in the main routine ZGEQP3RK. Constraint: 1 <= KP1 <= N_orig_mat. 🌟
  • MAXC2NRM — DOUBLE PRECISION. The maximum column 2-norm of the whole original matrix A_orig, computed in the main routine ZGEQP3RK. Constraint: MAXC2NRM >= 0. 🔥
  • A — COMPLEX*16 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 array TAU represent the unitary matrix Q(K) as a product of elementary reflectors.
  2. The upper triangular block of matrix A stored in A(IOFFSET+1:M,1:K) is the triangular factor obtained.
  3. The block of matrix A stored in A(1:IOFFSET,1:N) has been accordingly pivoted, but not factorized.
  4. The rest of 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 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)**H. 💖
  • LDA — INTEGER. The leading dimension of array A. Constraint: LDA >= max(1,M). 🎀
  • K — INTEGER. Factorization rank of matrix A, i.e. the rank of factor R, which is the same as the number of non-zero rows of factor R. Constraint: 0 <= K <= min(M-IOFFSET,KMAX,N). Also, K represents the number of non-zero Householder vectors. 👑
  • MAXC2NRMK — DOUBLE PRECISION. The maximum column 2-norm of the residual matrix when the factorization stopped at rank K. Constraint: MAXC2NRMK >= 0. 🌈
  • RELMAXC2NRMK — 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. Constraint: RELMAXC2NRMK >= 0. 🦋
  • JPIV — INTEGER array, dimension (N). Column pivot indices: for 1 <= j <= N, column j of matrix A was interchanged with column JPIV(j). 💅
  • TAU — COMPLEX*16 array, dimension (min(M-IOFFSET,N)). The scalar factors of the elementary reflectors. ✨
  • VN1 — DOUBLE PRECISION array, dimension (N). The vector with the partial column norms. 🍓
  • VN2 — DOUBLE PRECISION array, dimension (N). The vector with the exact column norms. 🍓
  • WORK — COMPLEX*16 array, dimension (N-1). Used in ZLARF subroutine to apply an elementary reflector from the left. 🧚
  • INFO — INTEGER. Exit / diagnostic code:
    • 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 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. 💀
    • 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 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 here and they are iconic — keep every single detail, no cap:

  1. [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. [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 🫶

and then the contributors block, served exactly like this:

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

Definition at line 341 of file zlaqp2rk.f.

👑 Author 👑

Generated automatically by Doxygen for LAPACK from the source code.

that’s the footer vibe, bestie: LAPACK Version 3.12.0, file /home/abui.../zlaqp2rk.f(3), with the source/version/date footer doing its generated little thing. 💅✨🫶

📦 where this page comes from