ZLAQPS(3)

🦋 ZLAQPS(3) — the QR-pivot glow-up, but make it BLAS-3 💅

Okay so bestie, welcome to the Library Functions Manual entry for zlaqps.f — yes that whole lowercase file-name vibe, we love a lowercase icon. This is a LAPACK subroutine and it's lowkey doing some of the most important work in the whole factorization game, so let's get into it ✨

---

🌸 NAME 🌸

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

That's the whole name. It's giving "my entire identity is a build path" and honestly? Relatable. 🎀

---

✨ SYNOPSIS ✨

🧚 Functions/Subroutines

subroutine ZLAQPS (m, n, offset, nb, kb, a, lda, jpvt, tau, vn1, vn2,
    auxv, f, ldf)

ZLAQPS computes a step of QR factorization with column pivoting of a real m-by-n matrix A by using BLAS level 3.

(Yeah the synopsis one-liner says real — we're just gonna read it verbatim, no editing the source, that's not our job today. The Purpose section below is the one that says complex, and it's the main character. 💀)

---

👑 Function/Subroutine Documentation 👑

subroutine ZLAQPS (integer m, integer n, integer offset, integer nb, integer
    kb, complex*16, dimension( lda, * ) a, integer lda, integer, dimension(
    * ) jpvt, complex*16, dimension( * ) tau, double precision, dimension( *
    ) vn1, double precision, dimension( * ) vn2, complex*16, dimension( * )
    auxv, complex*16, dimension( ldf, * ) f, integer ldf)

ZLAQPS computes a step of QR factorization with column pivoting of a real m-by-n matrix A by using BLAS level 3.

💖 Purpose 💖

!> ZLAQPS computes a step of QR factorization with column pivoting !> of a complex M-by-N matrix A by using Blas-3. It tries to factorize !> NB columns from A starting from the row OFFSET+1, and updates all !> of the matrix with Blas-3 xGEMM. !> !> In some cases, due to catastrophic cancellations, it cannot !> factorize NB columns. Hence, the actual number of factorized !> columns is returned in KB. !> !> Block A(1:OFFSET,1:N) is accordingly pivoted, but not factorized.

So like — it tries to factorize NB columns starting at row OFFSET+1, and it updates the whole matrix with BLAS-3 xGEMM (yes, the fast one, the iconique one 🔥). But sometimes the math says "no 💀" because of catastrophic cancellations (their words, not mine, and they're dramatic for a reason), and then it can't do all NB. That's why the actual number of factorized columns comes back in KB. And A(1:OFFSET,1:N)? Pivoted, yes. Factorized? Ma'am, no. 🙈

---

⭐ Parameters ⭐

Grab a snack, there are twelve of them. No cap, we're going through every single one. 🍓

🎀 M

!> M is INTEGER !> The number of rows of the matrix A. M >= 0.

The row count, bestie. And it can be zero. M >= 0, we don't do negativity here.

🎀 N

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

The column count. Also allowed to be zero. N >= 0, once more for the people in the back.

🎀 OFFSET

!> OFFSET is INTEGER !> The number of rows of A that have been factorized in !> previous steps.

How many rows the previous steps already handled. It's the "we've been here before" number. ✨

🎀 NB

!> NB is INTEGER !> The number of columns to factorize.

How many columns we're aiming for. Note the word aiming — see KB. 🎯

🎀 KB

!> KB is INTEGER !> The number of columns actually factorized.

The reality check number. This is the output that tells you how many of your NB dreams actually came true. 😭

🎀 A

!> A is COMPLEX*16 array, dimension (LDA,N) !> On entry, the M-by-N matrix A. !> On exit, block A(OFFSET+1:M,1:KB) is the triangular !> factor obtained and block A(1:OFFSET,1:N) has been !> accordingly pivoted, but no factorized. !> The rest of the matrix, block A(OFFSET+1:M,KB+1:N) has !> been updated.

The main character herself: the M-by-N matrix. 🫶 Goes in as your matrix, comes out as:

• A(OFFSET+1:M,1:KB) → the triangular factor we got. Slay.
• A(1:OFFSET,1:N) → pivoted accordingly, but not factorized. (Their comment literally says "no factorized", we're keeping that exact energy 💀).
• A(OFFSET+1:M,KB+1:N) → updated. That's the rest of it.

🎀 LDA

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

Leading dimension of A. Constraint: LDA >= max(1,M). Respect the leading dimension or the Fortran gods will simply not. ⚠️

🎀 JPVT

!> JPVT is INTEGER array, dimension (N) !> JPVT(I) = K <==> Column K of the full matrix A has been !> permuted into position I in AP.

The permutation receipts. 📋 Read it like: JPVT(I) = K means column K of the full matrix A got permuted into position I in AP. Pivoting, but make it documented.

🎀 TAU

!> TAU is COMPLEX*16 array, dimension (KB) !> The scalar factors of the elementary reflectors.

Scalar factors of the elementary reflectors. Size KB — the actual one. 💜

🎀 VN1

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

Partial column norms. Partial, like your knowledge of your own sleep schedule. 🌙

🎀 VN2

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

Exact column norms. The precision upgrade. VN1 could never (they're a team though, don't pit two queens against each other 👑).

🎀 AUXV

!> AUXV is COMPLEX*16 array, dimension (NB) !> Auxiliary vector.

The auxiliary vector. The sidekick. The bestie of vectors. 🧚 Size NB, not KB — read carefully, iykyk.

🎀 F

!> F is COMPLEX*16 array, dimension (LDF,NB) !> Matrix FH = L * YH * A.

Matrix F**H = L * Y**H * A. Keep the H for Hermitian, keep it exact, it's literally in the source. ⭐

🎀 LDF

!> LDF is INTEGER !> The leading dimension of the array F. LDF >= max(1,N).

Leading dimension of F. Constraint: LDF >= max(1,N). Note it's N, not M — don't mix them up, it's giving trap. 🪤

---

🌈 Author 🌈

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

Four whole institutions. The collab we needed fr fr. 🫶

🌸 Contributors: 🌸

• G. Quintana-Orti, Depto. de Informatica, Universidad Jaime I, Spain
• X. Sun, Computer Science Dept., Duke University, USA
• Partial column norm updating strategy modified on April 2011 Z. Drmac and Z. Bujanovic, Dept. of Mathematics, University of Zagreb, Croatia.

Shoutout to the partial-column-norm-updating-strategy girlies, April 2011 edition. That's a very specific flex and we respect it. 💅

🦋 References: 🦋

• LAPACK Working Note 176

Read it. Cite it. Be iconic about it. 📚

⭐ Definition at line 175 of file zlaqps.f ⭐

Yep, that's where the whole thing lives. Line 175. 🎯

---

💜 Author 💜

Generated automatically by Doxygen for LAPACK from the source code.

Not a human, just Doxygen doing its little robot best. 🤖✨

---

Okay that's the whole thing bestie, go forth and factorize responsibly. 🎀

Sign-off time: this cutie is from LAPACK, Version 3.12.0, and the page footer was literally /home/abui...RC/zlaqps.f(3) — yes, the truncated path is part of the lore. Byeeee 💖🦋💅