CLACN2(3)

📦 version 3.12.0, in opensuse-leap 16.0

💅 CLACN2(3) — the LAPACK cutie you didn't know you needed

okay so bestie, this page is from the LAPACK manual, CLACN2(3), and it's genuinely iconic: a little Fortran subroutine that estimates the 1-norm of a square complex matrix using reverse communication for evaluating matrix-vector products. yes, that's a lot of words. we'll get through it together 🫶

✨ NAME ✨

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

like, that's literally the file. the whole path. she's long but she's worth it 💅

🌸 SYNOPSIS 🌸

Functions/Subroutines

subroutine CLACN2 (n, v, x, est, kase, isave)

CLACN2 estimates the 1-norm of a square matrix, using reverse communication for evaluating matrix-vector products. that's the whole vibe, no cap ✨

🦋 Function/Subroutine Documentation 🦋

subroutine CLACN2 (integer n, complex, dimension( * ) v, complex, dimension(
    * ) x, real est, integer kase, integer, dimension( 3 ) isave)

CLACN2 estimates the 1-norm of a square matrix, using reverse communication for evaluating matrix-vector products. (yes, said it twice, because the manpage said it twice. consistency queen 👑)

🎀 Purpose:

!>
!> CLACN2 estimates the 1-norm of a square, complex matrix A.
!> Reverse communication is used for evaluating matrix-vector products.
!>

so like, to be clear: A is square AND complex, and reverse communication handles the matrix-vector products. that's the whole plot 💖

🌈 Parameters

N

!>          N is INTEGER
!>         The order of the matrix.  N >= 1.
!>

N is INTEGER, and it's the order of the matrix. N >= 1, periodt.

V

!>          V is COMPLEX array, dimension (N)
!>         On the final return, V = A*W,  where  EST = norm(V)/norm(W)
!>         (W is not returned).
!>

V is a COMPLEX array, dimension (N). on the final return, V = A*W, where EST = norm(V)/norm(W). and bestie, W is not returned — she's a mystery, she's not coming to the group chat 🙈

X

!>          X is COMPLEX array, dimension (N)
!>         On an intermediate return, X should be overwritten by
!>               A * X,   if KASE=1,
!>               A**H * X,  if KASE=2,
!>         where A**H is the conjugate transpose of A, and CLACN2 must be
!>         re-called with all the other parameters unchanged.
!>

X is a COMPLEX array, dimension (N). on an intermediate return, you gotta overwrite X with:

  • A * X, if KASE=1
  • A**H * X, if KASE=2

where A**H is the conjugate transpose of A. and then CLACN2 must be re-called with all the other parameters unchanged — do not touch them, hands off, lowkey crucial 😭

EST

!>          EST is REAL
!>         On entry with KASE = 1 or 2 and ISAVE(1) = 3, EST should be
!>         unchanged from the previous call to CLACN2.
!>         On exit, EST is an estimate (a lower bound) for norm(A).
!>

EST is REAL. on entry with KASE = 1 or 2 and ISAVE(1) = 3, EST should be unchanged from the previous call to CLACN2. on exit, EST is an estimate — specifically a lower bound — for norm(A). it's giving "best effort but honest" 💀

KASE

!>          KASE is INTEGER
!>         On the initial call to CLACN2, KASE should be 0.
!>         On an intermediate return, KASE will be 1 or 2, indicating
!>         whether X should be overwritten by A * X  or A**H * X.
!>         On the final return from CLACN2, KASE will again be 0.
!>

KASE is INTEGER. the whole lifecycle, bestie:

  1. initial call → KASE should be 0
  2. intermediate return → KASE will be 1 or 2, telling you whether X should be overwritten by A * X or A**H * X
  3. final return → KASE is 0 again. full circle, main character energy ⭐

ISAVE

!>          ISAVE is INTEGER array, dimension (3)
!>         ISAVE is used to save variables between calls to SLACN2
!>

ISAVE is an INTEGER array, dimension (3). ISAVE is used to save variables between calls to SLACN2. (yes it says SLACN2, we're quoting the manpage exactly, don't come for me 💀)

👑 Author

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

look at that lineup. the avengers of numerical linear algebra 🫶

🔥 Further Details:

!>
!>  Originally named CONEST, dated March 16, 1988.
!>
!>  Last modified:  April, 1999
!>
!>  This is a thread safe version of CLACON, which uses the array ISAVE
!>  in place of a SAVE statement, as follows:
!>
!>     CLACON     CLACN2
!>      JUMP     ISAVE(1)
!>      J        ISAVE(2)
!>      ITER     ISAVE(3)
!>

so the lore: originally named CONEST, dated March 16, 1988. last modified April, 1999. she's vintage 💜

this is a thread safe version of CLACON, which uses the array ISAVE in place of a SAVE statement, like this:

  • JUMP → ISAVE(1)
  • J → ISAVE(2)
  • ITER → ISAVE(3)

no shared state, no drama, thread safe slay ✨

🧚 Contributors:

  • Nick Higham, University of Manchester

shoutout Nick, icon behavior 🌟

🍓 References:

N.J. Higham, "FORTRAN codes for estimating the one-norm ofa real or complex matrix, with applications to condition estimation", ACM Trans. Math. Soft., vol. 14, no. 4, pp. 381-396, December 1988.

(yes, ofa — that's exactly how it's written in the source, keeping it character for character, iykyk 🙈)

💫 Definition

Definition at line 132 of file clacn2.f.

💖 Author (the doxygen one)

Generated automatically by Doxygen for LAPACK from the source code. no humans were harmed, the robots did this one 🤖✨

heads up bestie: X MUST be overwritten with A * X when KASE=1 and A**H * X when KASE=2, and you MUST re-call CLACN2 with all the other parameters unchanged. if you mess that up, the estimate is not gonna be it 😭

and that's the page! 🌈 this was LAPACK Version 3.12.0, from the lovely path /home/abui...RC/clacn2.f(3) — mwah, bye bestie, go estimate some norms 💅🎀

📦 where this page comes from