PCLASE2(l)

✨ NAME ✨

pclase2 — it sets up your distributed matrix sub( A ) (that's A(IA:IA+M-1,JA:JA+N-1)) so the diagonal is all BETA and the offdiagonals are all ALPHA. That's the whole job bestie, and it eats. 💅

---

🎀 SYNOPSIS 🎀

SUBROUTINE PCLASE2( UPLO, M, N, ALPHA, BETA, A, IA, JA, DESCA )

    CHARACTER       UPLO

    INTEGER         IA, JA, M, N

    COMPLEX         ALPHA, BETA

    INTEGER         DESCA( * )

    COMPLEX         A( * )

---

🦋 PURPOSE 🦋

ok so here's the vibe: PCLASE2 initializes an M-by-N distributed matrix sub( A ) — aka A(IA:IA+M-1,JA:JA+N-1) — setting it to BETA on the diagonal and ALPHA on the offdiagonals. 🌸

And PCLASE2 requires that only one dimension of the matrix operand is distributed. no cap. 😌

📝 Notes 📝

Every global data object out here has a description vector riding with it, and that vector is holding all the info you need to map an element of the object to its process and memory location. 💖

Let A be a generic term for any 2D block cyclicly distributed array. Such a global array has an associated description vector DESCA. And in the comments below, read the character _ as "of the global array". iykyk. 🧚

Here's the whole notation-to-descriptor situation:

• DTYPE_A (global) — stored in DESCA( DTYPE_ ) — the descriptor type. In this case, DTYPE_A = 1.
• CTXT_A (global) — stored in DESCA( CTXT_ ) — the BLACS context handle, indicating the BLACS process grid A is distributed over. The context itself is global, but the handle (the integer value) may vary. 🙈
• M_A (global) — stored in DESCA( M_ ) — the number of rows in the global array A.
• N_A (global) — stored in DESCA( N_ ) — the number of columns in the global array A.
• MB_A (global) — stored in DESCA( MB_ ) — the blocking factor used to distribute the rows of the array.
• NB_A (global) — stored in DESCA( NB_ ) — the blocking factor used to distribute the columns of the array.
• RSRC_A (global) — stored in DESCA( RSRC_ ) — the process row over which the first row of the array A is distributed.
• CSRC_A (global) — stored in DESCA( CSRC_ ) — the process column over which the first column of the array A is distributed.
• LLD_A (local) — stored in DESCA( LLD_ ) — the leading dimension of the local array. LLD_A >= MAX(1,LOCr(M_A)). ⭐

Now let K be the number of rows or columns of a distributed matrix, and assume its process grid has dimension p x q.

LOCr( K ) = the number of elements of K that a process would receive if K were distributed over the p processes of its process column.

Similarly, LOCc( K ) = the number of elements of K that a process would receive if K were distributed over the q processes of its process row.

You can get the values of LOCr() and LOCc() by calling the ScaLAPACK tool function NUMROC, like so:

LOCr( M ) = NUMROC( M, MB_A, MYROW, RSRC_A, NPROW ),
LOCc( N ) = NUMROC( N, NB_A, MYCOL, CSRC_A, NPCOL ).

And an upper bound for these quantities may be computed by:

LOCr( M ) <= ceil( ceil(M/MB_A)/NPROW )*MB_A
LOCc( N ) <= ceil( ceil(N/NB_A)/NPCOL )*NB_A

---

💅 ARGUMENTS 💅

• UPLO (global input) CHARACTER — specifies which part of the distributed matrix sub( A ) gets set:
  • = 'U': the upper triangular part is set; the strictly lower triangular part of sub( A ) is not changed. 🫶
  • = 'L': the lower triangular part is set; the strictly upper triangular part of sub( A ) is not changed.
  • Otherwise: all of the matrix sub( A ) is set. 🔥
• M (global input) INTEGER — the number of rows to be operated on, i.e. the number of rows of the distributed submatrix sub( A ). M >= 0.
• N (global input) INTEGER — the number of columns to be operated on, i.e. the number of columns of the distributed submatrix sub( A ). N >= 0.
• ALPHA (global input) COMPLEX — the constant the offdiagonal elements get set to.
• BETA (global input) COMPLEX — the constant the diagonal elements get set to.
• A (local output) COMPLEX pointer into the local memory to an array of dimension (LLD_A,LOCc(JA+N-1)). This array contains the local pieces of the distributed matrix sub( A ) to be set. On exit, the leading M-by-N submatrix sub( A ) is set like this:

if UPLO = 'U', A(IA+i-1,JA+j-1) = ALPHA, 1<=i<=j-1, 1<=j<=N, if
UPLO = 'L', A(IA+i-1,JA+j-1) = ALPHA, j+1<=i<=M, 1<=j<=N,
otherwise,     A(IA+i-1,JA+j-1) = ALPHA, 1<=i<=M, 1<=j<=N,
IA+i.NE.JA+j, and, for all UPLO, A(IA+i-1,JA+i-1) = BETA,
1<=i<=min(M,N).

• IA (global input) INTEGER — the row index in the global array A indicating the first row of sub( A ).
• JA (global input) INTEGER — the column index in the global array A indicating the first column of sub( A ).
• DESCA (global and local input) INTEGER array of dimension DLEN_. The array descriptor for the distributed matrix A. 💜

---

🫶 that's the whole page bestie, every flag, every default, nothing skipped, periodt.

💖 this was LAPACK auxiliary routine, version 1.5, dated 12 May 1997 💖 — shoutout to the LAPACK girlies who wrote it, mwah, iconic behavior, no notes. 👑✨