/home/abui...N/clarot.f(3)

🌸 CLAROT — from the Library Functions Manual 💅

okay bestie, so this page is literally /home/abui...N/clarot.f(3) and it's the glow-up doc for a Fortran subroutine that's lowkey iconic. Buckle up 🎀

---

✨ NAME ✨

/home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/TESTING/MATGEN/clarot.f

yes, that's the whole name. it's giving "my full legal name on the birth certificate." no cap. 💀

---

🦋 SYNOPSIS 🦋

Functions/Subroutines

subroutine CLAROT (lrows, lleft, lright, nl, c, s, a, lda, xleft,
    xright)

CLAROT — that's her. that's the main character. 👑

---

🌈 Function/Subroutine Documentation 🌈

subroutine CLAROT (logical lrows, logical lleft, logical lright, integer nl,
    complex c, complex s, complex, dimension( * ) a, integer lda, complex
    xleft, complex xright)

CLAROT ✨ (again, for the people in the back)

💖 Purpose 💖

!> !> CLAROT applies a (Givens) rotation to two adjacent rows or !> columns, where one element of the first and/or last column/row !> for use on matrices stored in some format other than GE, so !> that elements of the matrix may be used or modified for which !> no array element is provided. !> !> One example is a symmetric matrix in SB format (bandwidth=4), for !> which UPLO='L': Two adjacent rows will have the format: !> !> row j: C> C> C> C> C> . . . . !> row j+1: C> C> C> C> C> . . . . !> !> '*' indicates elements for which storage is provided, !> '.' indicates elements for which no storage is provided, but !> are not necessarily zero; their values are determined by !> symmetry. ' ' indicates elements which are necessarily zero, !> and have no storage provided. !> !> Those columns which have two '*'s can be handled by SROT. !> Those columns which have no '*'s can be ignored, since as long !> as the Givens rotations are carefully applied to preserve !> symmetry, their values are determined. !> Those columns which have one '*' have to be handled separately, !> by using separate variables and : !> !> row j: C> C> C> C> C> p . . . !> row j+1: q C> C> C> C> C> . . . . !> !> The element p would have to be set correctly, then that column !> is rotated, setting p to its new value. The next call to !> CLAROT would rotate columns j and j+1, using p, and restore !> symmetry. The element q would start out being zero, and be !> made non-zero by the rotation. Later, rotations would presumably !> be chosen to zero q out. !> !> Typical Calling Sequences: rotating the i-th and (i+1)-st rows. !> ------- ------- --------- !> !> General dense matrix: !> !> CALL CLAROT(.TRUE.,.FALSE.,.FALSE., N, C,S, !> A(i,1),LDA, DUMMY, DUMMY) !> !> General banded matrix in GB format: !> !> j = MAX(1, i-KL ) !> NL = MIN( N, i+KU+1 ) + 1-j !> CALL CLAROT( .TRUE., i-KL.GE.1, i+KU.LT.N, NL, C,S, !> A(KU+i+1-j,j),LDA-1, XLEFT, XRIGHT ) !> !> [ note that i+1-j is just MIN(i,KL+1) ] !> !> Symmetric banded matrix in SY format, bandwidth K, !> lower triangle only: !> !> j = MAX(1, i-K ) !> NL = MIN( K+1, i ) + 1 !> CALL CLAROT( .TRUE., i-K.GE.1, .TRUE., NL, C,S, !> A(i,j), LDA, XLEFT, XRIGHT ) !> !> Same, but upper triangle only: !> !> NL = MIN( K+1, N-i ) + 1 !> CALL CLAROT( .TRUE., .TRUE., i+K.LT.N, NL, C,S, !> A(i,i), LDA, XLEFT, XRIGHT ) !> !> Symmetric banded matrix in SB format, bandwidth K, !> lower triangle only: !> !> [ same as for SY, except:] !> . . . . !> A(i+1-j,j), LDA-1, XLEFT, XRIGHT ) !> !> [ note that i+1-j is just MIN(i,K+1) ] !> !> Same, but upper triangle only: !> . . . !> A(K+1,i), LDA-1, XLEFT, XRIGHT ) !> !> Rotating columns is just the transpose of rotating rows, except !> for GB and SB: (rotating columns i and i+1) !> !> GB: !> j = MAX(1, i-KU ) !> NL = MIN( N, i+KL+1 ) + 1-j !> CALL CLAROT( .TRUE., i-KU.GE.1, i+KL.LT.N, NL, C,S, !> A(KU+j+1-i,i),LDA-1, XTOP, XBOTTM ) !> !> [note that KU+j+1-i is just MAX(1,KU+2-i)] !> !> SB: (upper triangle) !> !> . . . . . . !> A(K+j+1-i,i),LDA-1, XTOP, XBOTTM ) !> !> SB: (lower triangle) !> !> . . . . . . !> A(1,i),LDA-1, XTOP, XBOTTM ) !>

okay tiny side note 🫶 — in the line by using separate variables and : the manpage literally has blanks where names should be. not me fixing it, not me guessing. it is what it is, bestie. 😭

---

🧚 OPTIONS / PARAMETERS 🧚 (the arguments, in order, no skipping)

!> LROWS - LOGICAL !> If .TRUE., then CLAROT will rotate two rows. If .FALSE., !> then it will rotate two columns. !> Not modified.

lrows — logical. .TRUE. means we're rotating two rows, .FALSE. means two columns. she does not get modified. 💅

!> LLEFT - LOGICAL !> If .TRUE., then XLEFT will be used instead of the !> corresponding element of A for the first element in the !> second row (if LROWS=.FALSE.) or column (if LROWS=.TRUE.) !> If .FALSE., then the corresponding element of A will be !> used. !> Not modified.

lleft — logical. .TRUE. → XLEFT gets used instead of the matching element of A, for the first element in the second row (when LROWS=.FALSE.) or column (when LROWS=.TRUE.). .FALSE. → just use the element of A. also not modified. 🎀

!> LRIGHT - LOGICAL !> If .TRUE., then XRIGHT will be used instead of the !> corresponding element of A for the last element in the !> first row (if LROWS=.FALSE.) or column (if LROWS=.TRUE.) If !> .FALSE., then the corresponding element of A will be used. !> Not modified.

lright — logical. .TRUE. → XRIGHT gets used instead of the matching element of A, for the last element in the first row (when LROWS=.FALSE.) or column (when LROWS=.TRUE.). .FALSE. → use the element of A. not modified. ✨

!> NL - INTEGER !> The length of the rows (if LROWS=.TRUE.) or columns (if !> LROWS=.FALSE.) to be rotated. If XLEFT and/or XRIGHT are !> used, the columns/rows they are in should be included in !> NL, e.g., if LLEFT = LRIGHT = .TRUE., then NL must be at !> least 2. The number of rows/columns to be rotated !> exclusive of those involving XLEFT and/or XRIGHT may !> not be negative, i.e., NL minus how many of LLEFT and !> LRIGHT are .TRUE. must be at least zero; if not, XERBLA !> will be called. !> Not modified.

nl — integer. the length of the rows (when LROWS=.TRUE.) or columns (when LROWS=.FALSE.) being rotated. if XLEFT and/or XRIGHT are in play, the columns/rows they live in count toward NL — so like, if LLEFT = LRIGHT = .TRUE., then NL has to be at least 2. the count of rows/columns rotated excluding the XLEFT/XRIGHT ones can't go negative — i.e. NL minus however many of LLEFT and LRIGHT are .TRUE. must be at least zero. if not, XERBLA gets called and it's over for you 😭. not modified.

!> C, S - COMPLEX !> Specify the Givens rotation to be applied. If LROWS is !> true, then the matrix ( c s ) !> ( _ _ ) !> (-s c ) is applied from the left; !> if false, then the transpose (not conjugated) thereof is !> applied from the right. Note that in contrast to the !> output of CROTG or to most versions of CROT, both C and S !> are complex. For a Givens rotation, |C|**2 + |S|**2 should !> be 1, but this is not checked. !> Not modified.

c, s — complex. these specify the Givens rotation being applied. if LROWS is true, this matrix gets applied from the left:

( c  s )
( _  _ )
(-s  c )

if false, the transpose (and not the conjugate) of that gets applied from the right. 🌀 key tea: unlike the output of CROTG or most versions of CROT, both C and S are complex. for a Givens rotation, |C|**2 + |S|**2 should be 1 — but bestie, this is not checked. 🙈 not modified.

!> A - COMPLEX array. !> The array containing the rows/columns to be rotated. The !> first element of A should be the upper left element to !> be rotated. !> Read and modified.

a — complex array. holds the rows/columns being rotated. the first element of A should be the upper left element to be rotated. read and modified. 🔥

!> LDA - INTEGER !> The leading dimension of A. If A contains !> a matrix stored in GE, HE, or SY format, then this is just !> the leading dimension of A as dimensioned in the calling !> routine. If A contains a matrix stored in band (GB, HB, or !> SB) format, then this should be *one less* than the leading !> dimension used in the calling routine. Thus, if A were !> dimensioned A(LDA,*) in CLAROT, then A(1,j) would be the !> j-th element in the first of the two rows to be rotated, !> and A(2,j) would be the j-th in the second, regardless of !> how the array may be stored in the calling routine. [A !> cannot, however, actually be dimensioned thus, since for !> band format, the row number may exceed LDA, which is not !> legal FORTRAN.] !> If LROWS=.TRUE., then LDA must be at least 1, otherwise !> it must be at least NL minus the number of .TRUE. values !> in XLEFT and XRIGHT. !> Not modified.

lda — integer. the leading dimension of A. if A holds a matrix in GE, HE, or SY format, this is just the leading dimension of A as dimensioned in the calling routine. if A holds a matrix in band (GB, HB, or SB) format, then this should be one less than the leading dimension used in the calling routine. so if A were dimensioned A(LDA,*) in CLAROT, then A(1,j) would be the j-th element in the first of the two rows to be rotated and A(2,j) would be the j-th in the second — no matter how the array is actually stored in the calling routine. ⚠️ BUT: A can't actually be dimensioned that way, because in band format the row number may exceed LDA, and that is not legal FORTRAN. if LROWS=.TRUE., then LDA must be at least 1; otherwise it must be at least NL minus the number of .TRUE. values in XLEFT and XRIGHT. not modified. 💜

!> XLEFT - COMPLEX !> If LLEFT is .TRUE., then XLEFT will be used and modified !> instead of A(2,1) (if LROWS=.TRUE.) or A(1,2) !> (if LROWS=.FALSE.). !> Read and modified.

xleft — complex. if LLEFT is .TRUE., then XLEFT gets used and modified instead of A(2,1) (when LROWS=.TRUE.) or A(1,2) (when LROWS=.FALSE.). read and modified. 🌸

!> XRIGHT - COMPLEX !> If LRIGHT is .TRUE., then XRIGHT will be used and modified !> instead of A(1,NL) (if LROWS=.TRUE.) or A(NL,1) !> (if LROWS=.FALSE.). !> Read and modified.

xright — complex. if LRIGHT is .TRUE., then XRIGHT gets used and modified instead of A(1,NL) (when LROWS=.TRUE.) or A(NL,1) (when LROWS=.FALSE.). read and modified. 🦋

---

👑 Author 👑

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

📍 Definition

at line 227 of file clarot.f. slay. ✨

---

💫 Author (yes, again) 💫

Generated automatically by Doxygen for LAPACK from the source code. it wrote its own about-me. iconic. 🎀

---

okay that's the whole page, bestie — go forth and rotate some rows (or columns, depending on LROWS). remember: |C|**2 + |S|**2 should be 1 and nobody is checking. 💅✨

mwah 💖 — with love, LAPACK, Version 3.12.0, serving you from /home/abui...N/clarot.f(3) 🫶