SRC/zggglm.f(3)

💅 SRC/zggglm.f(3) — like, the LAPACK Library Functions Manual, bestie ✨

okay so. welcome to SRC/zggglm.f(3), a page from the LAPACK Library Functions Manual, and it's giving "big math energy, tiny file" 🎀 let's get into it.

---

🌸 NAME 🌸

SRC/zggglm.f — that's literally it, that's the whole name section. iconic minimalism 💅

---

✨ SYNOPSIS ✨

🦋 Functions/Subroutines 🦋

• subroutine zggglm (n, m, p, a, lda, b, ldb, d, x, y, work, lwork, info) — also known as ZGGGLM, which is honestly such a main character name 👑

---

💖 Function/Subroutine Documentation 💖

🫶 the actual signature, no cap 🫶

subroutine zggglm (integer n, integer m, integer p, complex*16, dimension(
    lda, * ) a, integer lda, complex*16, dimension( ldb, * ) b, integer ldb,
    complex*16, dimension( * ) d, complex*16, dimension( * ) x, complex*16,
    dimension( * ) y, complex*16, dimension( * ) work, integer lwork,
    integer info)

ZGGGLM 🧚

---

🔥 Purpose: 🔥

so like. here's the whole vibe, straight from the source:

!>
!> ZGGGLM solves a general Gauss-Markov linear model (GLM) problem:
!>
!>         minimize || y ||_2   subject to   d = A*x + B*y
!>             x
!>
!> where A is an N-by-M matrix, B is an N-by-P matrix, and d is a
!> given N-vector. It is assumed that M <= N <= M+P, and
!>
!>            rank(A) = M    and    rank( A B ) = N.
!>
!> Under these assumptions, the constrained equation is always
!> consistent, and there is a unique solution x and a minimal 2-norm
!> solution y, which is obtained using a generalized QR factorization
!> of the matrices (A, B) given by
!>
!>    A = Q*(R),   B = Q*T*Z.
!>          (0)
!>
!> In particular, if matrix B is square nonsingular, then the problem
!> GLM is equivalent to the following weighted linear least squares
!> problem
!>
!>              minimize || inv(B)*(d-A*x) ||_2
!>                  x
!>
!> where inv(B) denotes the inverse of B.
!>
!> Callers of this subroutine should note that the singularity/rank-deficiency checks
!> implemented in this subroutine are rudimentary. The ZTRTRS subroutine called by this
!> subroutine only signals a failure due to singularity if the problem is exactly singular.
!>
!> It is conceivable for one (or more) of the factors involved in the generalized QR
!> factorization of the pair (A, B) to be subnormally close to singularity without this
!> subroutine signalling an error. The solutions computed for such almost-rank-deficient
!> problems may be less accurate due to a loss of numerical precision.
!>
!>

⚠️ okay bestie, real talk for a sec — the singularity/rank-deficiency checks in here are rudimentary. ZTRTRS only yells at you if the problem is exactly singular. so if one (or more) of the factors in the generalized QR factorization of (A, B) is subnormally close to singular without triggering an error? no signal, no drama, but the solutions you get for those almost-rank-deficient problems may be less accurate because of a loss of numerical precision. fr fr. 🫶

---

🌈 Parameters 🌈

N

!>          N is INTEGER
!>          The number of rows of the matrices A and B.  N >= 0.
!>

the row count for A and B, and yeah N >= 0.

M

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

how many columns A has. 0 <= M <= N. 🍓

P

!>          P is INTEGER
!>          The number of columns of the matrix B.  P >= N-M.
!>

how many columns B has. P >= N-M, periodt.

A

!>          A is COMPLEX*16 array, dimension (LDA,M)
!>          On entry, the N-by-M matrix A.
!>          On exit, the upper triangular part of the array A contains
!>          the M-by-M upper triangular matrix R.
!>

you come in as the N-by-M matrix A, and you leave with the upper triangular part of A holding the M-by-M upper triangular matrix R. glow-up 💅

LDA

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

the leading dimension of A. LDA >= max(1,N). don't skip this.

B

!>          B is COMPLEX*16 array, dimension (LDB,P)
!>          On entry, the N-by-P matrix B.
!>          On exit, if N <= P, the upper triangle of the subarray
!>          B(1:N,P-N+1:P) contains the N-by-N upper triangular matrix T;
!>          if N > P, the elements on and above the (N-P)th subdiagonal
!>          contain the N-by-P upper trapezoidal matrix T.
!>

in: the N-by-P matrix B. out, and this is the part where the vibes split 😭 — if N <= P, the upper triangle of the subarray B(1:N,P-N+1:P) contains the N-by-N upper triangular matrix T; if N > P, the elements on and above the (N-P)th subdiagonal contain the N-by-P upper trapezoidal matrix T. both valid, both iconic.

LDB

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

leading dimension of B. LDB >= max(1,N). same rules, different letter.

D

!>          D is COMPLEX*16 array, dimension (N)
!>          On entry, D is the left hand side of the GLM equation.
!>          On exit, D is destroyed.
!>

in: D is the left hand side of the GLM equation, the moment. out: D is destroyed. 💀 like, gone. that's the deal, don't be surprised.

X

!>          X is COMPLEX*16 array, dimension (M)
!>

COMPLEX*16 array, dimension (M). that's the whole note, she's chill like that.

Y

!>          Y is COMPLEX*16 array, dimension (P)
!>
!>          On exit, X and Y are the solutions of the GLM problem.
!>

COMPLEX*16, dimension (P). and okay here's the payoff: on exit, X and Y are the solutions of the GLM problem 🎉 we love a reveal.

WORK

!>          WORK is COMPLEX*16 array, dimension (MAX(1,LWORK))
!>          On exit, if INFO = 0, WORK(1) returns the optimal LWORK.
!>

COMPLEX*16, dimension (MAX(1,LWORK)). on exit, if INFO = 0, then WORK(1) returns the optimal LWORK. cute lil bonus info 🌸

LWORK

!>          LWORK is INTEGER
!>          The dimension of the array WORK. LWORK >= max(1,N+M+P).
!>          For optimum performance, LWORK >= M+min(N,P)+max(N,P)*NB,
!>          where NB is an upper bound for the optimal blocksizes for
!>          ZGEQRF, ZGERQF, ZUNMQR and ZUNMRQ.
!>
!>          If LWORK = -1, then a workspace query is assumed; the routine
!>          only calculates the optimal size of the WORK array, returns
!>          this value as the first entry of the WORK array, and no error
!>          message related to LWORK is issued by XERBLA.
!>

dimension of the WORK array, minimum LWORK >= max(1,N+M+P). for optimum performance you want LWORK >= M+min(N,P)+max(N,P)*NB, where NB is an upper bound for the optimal blocksizes for ZGEQRF, ZGERQF, ZUNMQR and ZUNMRQ 🔥 (four whole routines, she's well-connected).

and if LWORK = -1? that's a full-on workspace query — the routine only calculates the optimal size of the WORK array, returns this value as the first entry of the WORK array, and no error message related to LWORK is issued by XERBLA. just vibes and a number ✨

INFO

!>          INFO is INTEGER
!>          = 0:  successful exit.
!>          < 0:  if INFO = -i, the i-th argument had an illegal value.
!>          = 1:  the upper triangular factor R associated with A in the
!>                generalized QR factorization of the pair (A, B) is exactly
!>                singular, so that rank(A) < M; the least squares
!>                solution could not be computed.
!>          = 2:  the bottom (N-M) by (N-M) part of the upper trapezoidal
!>                factor T associated with B in the generalized QR
!>                factorization of the pair (A, B) is exactly singular, so that
!>                rank( A B ) < N; the least squares solution could not
!>                be computed.
!>

the whole mood report, let's break it down:

• = 0: successful exit. slay 🎀
• < 0: if INFO = -i, the i-th argument had an illegal value. someone passed something wrong, and it wasn't you (it was you).
• = 1: the upper triangular factor R associated with A in the generalized QR factorization of the pair (A, B) is exactly singular, so that rank(A) < M; the least squares solution could not be computed. 😭
• = 2: the bottom (N-M) by (N-M) part of the upper trapezoidal factor T associated with B in the generalized QR factorization of the pair (A, B) is exactly singular, so that rank( A B ) < N; the least squares solution could not be computed. also 😭

---

👑 Author 👑

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

a whole squad, honestly 🫶

📖 Definition at line 193 of file zggglm.f.

---

💜 Author 💜

Generated automatically by Doxygen for LAPACK from the source code. not me being auto-generated and still having this much personality 💅✨

---

okay that's the page!! hope you understood it bestie, you're gonna do amazing 🦋🌸💖

— cute lil sign-off: this page comes from LAPACK, Version 3.12.0, and it's the SRC/zggglm.f(3) page, mwah 😘 🎀