SRC/cgelq.f(3)

📦
version 3.12.1 · 5 versions
, in arch rolling

💅 SRC/cgelq.f(3) — Library Functions Manual, but make it cute

okay bestie, so this is a page straight out of the Library Functions Manual — it's SRC/cgelq.f(3), and it's all about one iconic little subroutine. Buckle up, she's giving linear algebra but make it ✨aesthetic✨.

🌸 NAME 🌸

SRC/cgelq.f — no cap, that's literally the whole name. Short queen behavior.

🦋 SYNOPSIS 🦋

Functions/Subroutines

  • subroutine cgelq (m, n, a, lda, t, tsize, work, lwork, info) — this is the queen herself, CGELQ

Function/Subroutine Documentation

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

CGELQ 💖 — that's the full signature, every argument accounted for, we don't drop a single one.

✨ Purpose ✨

!> she computes an LQ factorization of a complex M-by-N matrix A, and it's giving:

!>    A = ( L 0 ) * Q

where:

!>    Q is a N-by-N orthogonal matrix;
!>    L is a lower-triangular M-by-M matrix;
!>    0 is a M-by-(N-M) zero matrix, if M < N.

like, that's the whole vibe. Q is orthogonal and iconic, L is lower-triangular and doing her thing, and the 0 block is giving "nothing to see here" when M < N. 🫶

🎀 Parameters 🎀

M

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

so, like, the row count. keep it >= 0, no negative vibes allowed.

N

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

column count, also >= 0. slay.

A

!> A is COMPLEX array, dimension (LDA,N) !> On entry, the M-by-N matrix A. !> On exit, the elements on and below the diagonal of the array !> contain the M-by-min(M,N) lower trapezoidal matrix L !> (L is lower triangular if M <= N); !> the elements above the diagonal are used to store part of the !> data structure to represent Q.

bestie, this is the main character array. you hand her the M-by-N matrix A going in, and coming out the diagonal and below hold the M-by-min(M,N) lower trapezoidal L (and like, she's plain lower triangular if M <= N 💅), while the stuff above the diagonal gets repurposed to stash part of the data structure that represents Q. not me reusing storage 😭 that's efficiency, periodt.

LDA

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

leading dimension of A, and she better be >= max(1,M). no exceptions.

T

!> T is COMPLEX 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.

so on exit, if INFO = 0, T(1) gives you back the optimal TSIZE (or minimal-or-optimal, depending on whether a query was assumed — check TSIZE, iykyk). the rest of T carries part of the data structure for Q. if you actually want to apply or construct Q, you have to keep T (alongside A) and pass it along to further subroutines. don't lose her 💀

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

the rules, spelled out:

  • TSIZE >= 5 → that's the dimension of the array T.
  • TSIZE = -1 or -2 → workspace query time, babes. the routine only computes the sizes of the T and WORK arrays, returns those values as the first entries of the T and WORK arrays, and no error message about T or WORK gets issued by XERBLA. (yep, XERBLA stays quiet for this one 🤫)
  • TSIZE = -1 → optimal size of T for optimum performance, dropped into T(1).
  • TSIZE = -2 → minimal size of T, also dropped into T(1).

WORK

!> (workspace) COMPLEX 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.

workspace array, dimension (MAX(1,LWORK)). on exit with INFO = 0, WORK(1) holds the optimal LWORK (or minimal-or-optimal if a query was assumed). details live in LWORK, scroll down bestie.

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

same energy, different array:

  • dimension of the array WORK, and LWORK >= 1. non-negotiable.
  • LWORK = -1 or -2 → workspace query assumed. only the sizes of T and WORK get computed, returned as the first entries of the T and WORK arrays, and XERBLA issues no error message related to T or WORK.
  • LWORK = -1 → optimal size of WORK for optimal performance, returned in WORK(1).
  • LWORK = -2 → minimal size of WORK, returned in WORK(1).

INFO

!> INFO is INTEGER !> = 0: successful exit !> < 0: if INFO = -i, the i-th argument had an illegal value

the receipts:

  • = 0 → successful exit, we ate 🍓
  • < 0 → if INFO = -i, the i-th argument had an illegal value. someone fumbled an argument, go check arg number i.

👑 Author 👑

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

four absolute legends. we stan. 🌈

💜 Further Details 💜

!> The goal of the interface is to give maximum freedom to the developers for !> creating any LQ factorization algorithm they wish. The triangular !> (trapezoidal) L has to be stored in the lower 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.

the whole design philosophy is freedom — devs can build whatever LQ factorization algorithm they want. the constraints: the triangular (trapezoidal) L has to live in the lower part of A. the lower part of A plus the array T are fair game for storing anything relevant to applying or constructing the Q factor. and WORK? you can safely yeet it after exit, she's done her job 💅

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

⚠️ Caution, fr fr: do NOT expect the sizes of T and WORK to match across different LAPACK implementations — or even between two different executions. you need a workspace query (for T and WORK) at each execution. the one comfort: within a given execution, the sizes of T and WORK are fixed and won't change from one query to the next. 🫶

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.

read the room: these are implementation-specific. do not take them for granted — they might change in the future and probably won't hold for a different LAPACK implementation. they're here in case you want to peek at 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
!>                           CLASWLQ or CGELQT

!> Depending on the matrix dimensions M and N, and row and column !> block sizes MB and NB returned by ILAENV, CGELQ will use either !> CLASWLQ (if the matrix is short-and-wide) or CGELQT to compute !> the LQ factorization.

so in this version: T(2) is the row block size (MB), T(3) is the column block size (NB), and T(6:TSIZE) holds the data structure needed for Q, computed by CLASWLQ or CGELQT.

and depending on the matrix dimensions M and N, plus the row and column block sizes MB and NB that ILAENV hands back, CGELQ picks either CLASWLQ (when the matrix is short-and-wide, iconic) or CGELQT to compute that LQ factorization. the way she chooses 😭 she contains multitudes.

Definition at line 172 of file cgelq.f.

🌟 Author (the auto-generated one) 🌟

Generated automatically by Doxygen for LAPACK from the source code. not a human, just vibes and a parser. 🧚

okay that's the whole page bestie, every flag and every detail intact, no cap 💖 this was SRC/cgelq.f(3) from LAPACK Version 3.12.0 — now go forth and factorize responsibly, mwah 💅✨🎀

📦 where this page comes from