SRC/sgeqr.f(3)

📦
version 3.12.1 · 4 versions
, in arch rolling

✨ SRC/sgeqr.f ✨

okay bestie, this page is from the <pink>LAPACK</pink> manual, and it's literally the glow-up guide for sgeqr 💅 a Fortran subroutine that does QR factorization and hands you back the Q data structure like a little gift 🎀

🌸 NAME 🌸

SRC/sgeqr.f — no cap, that's the whole name. It's giving "file path as a title" energy and honestly? iconic.

🦋 SYNOPSIS 🦋

Functions/Subroutines

  • subroutine sgeqr (m, n, a, lda, t, tsize, work, lwork, info) — the one, the only, SGEQR ✨

👑 Function/Subroutine Documentation 👑

subroutine sgeqr (integer m, integer n, real, dimension( lda, * ) a, integer
    lda, real, dimension( * ) t, integer tsize, real, dimension( * ) work,
    integer lwork, integer info)

SGEQR — she's the main character fr fr 🌈

💖 Purpose 💖

!>
!> SGEQR computes a QR factorization of a real M-by-N matrix A:
!>
!>    A = Q * ( R ),
!>            ( 0 )
!>
!> where:
!>
!>    Q is a M-by-M orthogonal matrix;
!>    R is an upper-triangular N-by-N matrix;
!>    0 is a (M-N)-by-N zero matrix, if M > N.
!>
!>

so basically A gets factored into Q times that stacked ( R ) over ( 0 ) situation, and yes the zero block is only a thing when M > N 🫶

🧚 Parameters 🧚

okay let's go through the whole squad one by one, no skipping, we don't do that here 💜

  • M — M is INTEGER. The number of rows of the matrix A. M >= 0. that's it that's the row count bestie 💀
  • N — N is INTEGER. The number of columns of the matrix A. N >= 0. the column count, we love a non-negative queen 🌸
  • A — A is REAL array, dimension (LDA,N). On entry, the M-by-N matrix A. On exit, the elements on and above the diagonal of the array contain the min(M,N)-by-N upper trapezoidal matrix R (R is upper triangular if M >= N); the elements below the diagonal are used to store part of the data structure to represent Q. okay so she comes in as your matrix and leaves as R up top + sneaky Q data down below, highkey efficient ✨
  • LDA — LDA is INTEGER. The leading dimension of the array A. LDA >= max(1,M). respect the leading dimension or else 🙈
  • T — T is REAL array, dimension (MAX(5,TSIZE)). On exit, if INFO = 0, T(1) returns optimal (or either minimal or optimal, if query is assumed) TSIZE. See TSIZE for details. Remaining T contains part of the data structure used to represent Q. If one wants to apply or construct Q, then one needs to keep T (in addition to A) and pass it to further subroutines. 👑 keep T! like genuinely do not throw her away, she's part of the Q lore, she travels with A to the next subroutine, iykyk
  • TSIZE — TSIZE is INTEGER. If TSIZE >= 5, the dimension of the array T. If TSIZE = -1 or -2, then a workspace query is assumed. The routine only calculates the sizes of the T and WORK arrays, returns these values as the first entries of the T and WORK arrays, and no error message related to T or WORK is issued by XERBLA. If TSIZE = -1, the routine calculates optimal size of T for the optimum performance and returns this value in T(1). If TSIZE = -2, the routine calculates minimal size of T and returns this value in T(1). so -1 is the "give me the optimal slay" option and -2 is the "give me the minimal slay" option, choose your vibe 💅
  • WORK — (workspace) REAL array, dimension (MAX(1,LWORK)). On exit, if INFO = 0, WORK(1) contains optimal (or either minimal or optimal, if query was assumed) LWORK. See LWORK for details. 🫶 note that the WORK array itself can be yeeted after exit — she's just scratch, no feelings attached
  • LWORK — LWORK is INTEGER. The dimension of the array WORK. LWORK >= 1. If LWORK = -1 or -2, then a workspace query is assumed. The routine only calculates the sizes of the T and WORK arrays, returns these values as the first entries of the T and WORK arrays, and no error message related to T or WORK is issued by XERBLA. If LWORK = -1, the routine calculates optimal size of WORK for the optimal performance and returns this value in WORK(1). If LWORK = -2, the routine calculates minimal size of WORK and returns this value in WORK(1). yes the -1 / -2 query thing applies here too, she's consistent 💖
  • INFO — INFO is INTEGER.
    • = 0: successful exit 🎉
    • < 0: if INFO = -i, the i-th argument had an illegal value 😭

⭐ Author ⭐

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

the whole academic friend group co-signed this one, we stan 🌈

💀 Further Details 💀

!>
!> The goal of the interface is to give maximum freedom to the developers for
!> creating any QR factorization algorithm they wish. The triangular
!> (trapezoidal) R has to be stored in the upper part of A. The lower part of A
!> and the array T can be used to store any relevant information for applying or
!> constructing the Q factor. The WORK array can safely be discarded after exit.
!>
!> Caution: One should not expect the sizes of T and WORK to be the same from one
!> LAPACK implementation to the other, or even from one execution to the other.
!> A workspace query (for T and WORK) is needed at each execution. However,
!> for a given execution, the size of T and WORK are fixed and will not change
!> from one query to the next.
!>
!>

the whole point of this interface is maximum freedom for developers to build whatever QR algorithm they want — R (triangular/trapezoidal) lives in the upper part of A, the lower part of A plus T hold whatever they need for Q, and WORK can be safely discarded after exit 🧚

⚠️ Caution, for real: do not expect the sizes of T and WORK to match between LAPACK implementations, or even between one execution and the next 😭 you need a workspace query (for both T and WORK) at each execution. that said, for a given execution, the sizes of T and WORK are fixed and won't change from one query to the next, so at least she's loyal within a run 🫶

🌟 Further Details particular to this LAPACK implementation: 🌟

!>
!> These details are particular for this LAPACK implementation. Users should not
!> take them for granted. These details may change in the future, and are not likely
!> true for another LAPACK implementation. These details are relevant if one wants
!> to try to understand the code. They are not part of the interface.
!>
!> In this version,
!>
!>          T(2): row block size (MB)
!>          T(3): column block size (NB)
!>          T(6:TSIZE): data structure needed for Q, computed by
!>                           SLATSQR or SGEQRT
!>
!>  Depending on the matrix dimensions M and N, and row and column
!>  block sizes MB and NB returned by ILAENV, SGEQR will use either
!>  SLATSQR (if the matrix is tall-and-skinny) or SGEQRT to compute
!>  the QR factorization.
!>
!>

okay so this section is implementation tea — it's specific to this LAPACK build, don't take it for granted bestie, it might change in the future and it's probably not true for another LAPACK implementation 😳 these details are only relevant if you want to actually understand the code — they are not part of the interface.

in this version:

  • T(2): row block size (MB)
  • T(3): column block size (NB)
  • T(6:TSIZE): data structure needed for Q, computed by SLATSQR or SGEQRT

and depending on the matrix dimensions M and N, and row and column block sizes MB and NB returned by ILAENV, SGEQR will use either SLATSQR (if the matrix is tall-and-skinny 🦋) or SGEQRT to compute the QR factorization. she picks her algorithm based on your matrix's body type, lowkey iconic 💅

🎀 Definition at line 174 of file sgeqr.f. 🎀

line one-seven-four, if you were wondering where to find her in the source 👑

💜 Author 💜

Generated automatically by Doxygen for LAPACK from the source code. the robots wrote the docs, we just added the sparkle ✨

LAPACK — Version 3.12.0 — SRC/sgeqr.f(3)

and that's the whole page bestie 🫶 sgeqr said "I'll factor your QR, I'll keep my data in T, and I will absolutely make you do a workspace query every single execution" and honestly? respect the boundaries. mwah 💋

📦 where this page comes from