SRC/slaqp2rk.f(3)

📦

version 3.12.1 · 2 versions

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

💅 NAME 💅

SRC/slaqp2rk.f — okay bestie, this is a <pink>Library Functions Manual</pink> situation, and the star of the show is literally a Fortran subroutine living its best life in SRC/slaqp2rk.f. Periodt.

✨ SYNOPSIS ✨

🦋 Functions/Subroutines

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

So what does it do? SLAQP2RK computes a 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. That's the whole vibe. 🫶

🎀 Function/Subroutine Documentation 🎀

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

SLAQP2RK 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. Same energy as the synopsis, just wearing its full signature. 💖

🌸 Purpose

Okay so, the actual purpose — she's computing a truncated (rank K) or full rank Householder QR factorization with column pivoting of a real matrix block A(IOFFSET+1:M,1:N) like this:

  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. Lowkey important distinction, don't skip it. 🙈

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

🌈 Parameters 🌈

💜 M

M is INTEGER. The number of rows of the matrix A. M >= 0. That's it, that's the whole job.

💜 N

N is INTEGER. The number of columns of the matrix A. N >= 0. Iconic, no notes.

💜 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. So she's carrying history, main character energy fr. 👑

💜 KMAX

KMAX is INTEGER.

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-IOFFSET,N), then this stopping criterion is not used, and you 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.

Like, she literally leaves without touching anything. Respect the boundaries. 💀

💜 ABSTOL

ABSTOL is DOUBLE PRECISION, and 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, 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 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, 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 list goes a) then d). She skipped the middle letters, we don't ask questions, we just vibe. 🧚

💜 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 SGEQP3RK. 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 SGEQP3RK. MAXC2NRM >= 0.

💜 A

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

On entry, it's 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, bestie, it's a whole situation:

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.
The upper triangular block of the matrix A stored in A(IOFFSET+1:M,1:K) 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,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. Multi-tasking queen. ✨

💜 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 REAL array, dimension (min(M-IOFFSET,N)). The scalar factors of the elementary reflectors.

💜 VN1

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

💜 VN2

VN2 is REAL array, dimension (N). The vector with the exact column norms. (Yes, she's the precise one. We stan. 🍓)

💜 WORK

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

💜 INFO

INFO is INTEGER, and she has lore:

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

Case 2 is giving "we found a NaN and we're stopping right here", case 3 is giving "we found an infinity but we're seeing this through". Both are valid. 💅

Okay so reference [2] is the receipts moment for the partial column norm updating strategy: A partial column norm updating strategy developed in 2006. By Z. Drmac and Z. Bujanovic, Dept. of Math., University of Zagreb, Croatia. The paper title is On the failure of rank revealing QR factorization software – a case study. It’s LAPACK Working Note 176. and in ACM Trans. Math. Softw. 35, 2, Article 12 (July 2008), 28 pages. No cap, that citation is doing the most and we respect it 💅✨

🫶 Contributors 🫶

These are the literal source-comment lines, kept exactly as they appear:

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

And the page pins it down right here: Definition at line 340 of file slaqp2rk.f.

👑 Author 👑

This page? Generated automatically by Doxygen for LAPACK from the source code. Iconic automated behavior, honestly 🎀

And that’s the whole page, bestie: source SRC/slaqp2rk.f(3), LAPACK Version 3.12.0. The footer doesn’t hand us a date, so no invented timestamp — we stay accurate, periodt 💖✨

📦 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