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

📦 version 3.12.0, in opensuse-leap 16.0

okay so bestie, welcome to the Library Functions Manual page for slatmr.f(3) — the header is out here calling it /home/abui...N/slatmr.f(3), and the actual source path is in NAME below. 💅

🎀 NAME 🎀

  • /home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/TESTING/MATGEN/slatmr.f — that's the file this whole iconic page is about, no cap. ✨

✨ SYNOPSIS ✨

🌸 Functions/Subroutines 🌸

       subroutine SLATMR (m, n, dist, iseed, sym, d, mode, cond, dmax, rsign,
           grade, dl, model, condl, dr, moder, condr, pivtng, ipivot, kl, ku,
           sparse, anorm, pack, a, lda, iwork, info)
           SLATMR

🫶 Function/Subroutine Documentation 🫶

   subroutine SLATMR (integer m, integer n, character dist, integer, dimension(
       4 ) iseed, character sym, real, dimension( * ) d, integer mode, real
       cond, real dmax, character rsign, character grade, real, dimension( * )
       dl, integer model, real condl, real, dimension( * ) dr, integer moder,
       real condr, character pivtng, integer, dimension( * ) ipivot, integer
       kl, integer ku, real sparse, real anorm, character pack, real,
       dimension( lda, * ) a, integer lda, integer, dimension( * ) iwork,
       integer info)
       SLATMR

🎀 Purpose 🎀

okay so what does SLATMR actually do? It generates random matrices of various types for testing LAPACK programs. literally its whole main character job. 💖

It operates by applying this sequence of operations, bestie:

  1. Generate a matrix A with random entries of distribution DIST, which is symmetric if SYM='S', and nonsymmetric if SYM='N'.
  2. Set the diagonal to D, where D may be input or computed according to MODE, COND, DMAX and RSIGN as described below.
  3. Grade the matrix, if desired, from the left and/or right as specified by GRADE. The inputs DL, MODEL, CONDL, DR, MODER and CONDR also determine the grading as described below.
  4. Permute, if desired, the rows and/or columns as specified by PIVTNG and IPIVOT.
  5. Set random entries to zero, if desired, to get a random sparse matrix as specified by SPARSE.
  6. Make A a band matrix, if desired, by zeroing out the matrix outside a band of lower bandwidth KL and upper bandwidth KU.
  7. Scale A, if desired, to have maximum entry ANORM.
  8. Pack the matrix if desired. Options specified by PACK are:
    • no packing
    • zero out upper half (if symmetric)
    • zero out lower half (if symmetric)
    • store the upper half columnwise (if symmetric or square upper triangular)
    • store the lower half columnwise (if symmetric or square lower triangular) — same as upper half rowwise if symmetric
    • store the lower triangle in banded format (if symmetric)
    • store the upper triangle in banded format (if symmetric)
    • store the entire matrix in banded format
Note, bestie: If two calls to SLATMR differ only in the PACK parameter, they will generate mathematically equivalent matrices. ✨ If two calls to SLATMR both have full bandwidth (KL = M-1 and KU = N-1), and differ only in the PIVTNG and PACK parameters, then the matrices generated will differ only in the order of the rows and/or columns, and otherwise contain the same data. This consistency cannot be and is not maintained with less than full bandwidth. 🫶

🌈 Parameters 🌈

🍓 M 🍓

M is INTEGER. Number of rows of A. Not modified. 💅

🍓 N 🍓

N is INTEGER. Number of columns of A. Not modified. 💅

🦋 DIST 🦋

DIST is CHARACTER*1.

On entry, DIST specifies the type of distribution to be used to generate a random matrix:

  • 'U' => UNIFORM( 0, 1 ) ('U' for uniform)
  • 'S' => UNIFORM( -1, 1 ) ('S' for symmetric)
  • 'N' => NORMAL( 0, 1 ) ('N' for normal)

Not modified. ✨

🦋 ISEED 🦋

ISEED is INTEGER array, dimension (4).

On entry ISEED specifies the seed of the random number generator. They should lie between 0 and 4095 inclusive, and ISEED(4) should be odd. The random number generator uses a linear congruential sequence limited to small integers, and so should produce machine independent random numbers. The values of ISEED are changed on exit, and can be used in the next call to SLATMR to continue the same random number sequence. Changed on exit. 🎀

🦋 SYM 🦋

SYM is CHARACTER*1.

If SYM='S' or 'H', generated matrix is symmetric. If SYM='N', generated matrix is nonsymmetric. Not modified. 💜

🍓 D 🍓

D is REAL array, dimension (min(M,N)).

On entry this array specifies the diagonal entries of the diagonal of A. D may either be specified on entry, or set according to MODE and COND as described below. May be changed on exit if MODE is nonzero. 🌸

🍓 MODE 🍓

MODE is INTEGER.

On entry describes how D is to be used:

  • MODE = 0 means use D as input
  • MODE = 1 sets D(1)=1 and D(2:N)=1.0/COND
  • MODE = 2 sets D(1:N-1)=1 and D(N)=1.0/COND
  • MODE = 3 sets D(I)=COND**(-(I-1)/(N-1))
  • MODE = 4 sets D(i)=1 - (i-1)/(N-1)*(1 - 1/COND)
  • MODE = 5 sets D to random numbers in the range ( 1/COND , 1 ) such that their logarithms are uniformly distributed.
  • MODE = 6 set D to random numbers from same distribution as the rest of the matrix.

MODE < 0 has the same meaning as ABS(MODE), except that the order of the elements of D is reversed.

Thus if MODE is positive, D has entries ranging from 1 to 1/COND, if negative, from 1/COND to 1. Not modified. 💅

🍓 COND 🍓

COND is REAL.

On entry, used as described under MODE above. If used, it must be >= 1. Not modified. ✨

🦋 DMAX 🦋

DMAX is REAL.

If MODE neither -6, 0 nor 6, the diagonal is scaled by DMAX / max(abs(D(i))), so that maximum absolute entry of diagonal is abs(DMAX). If DMAX is negative (or zero), diagonal will be scaled by a negative number (or zero). 🫶

🦋 RSIGN 🦋

RSIGN is CHARACTER*1.

If MODE neither -6, 0 nor 6, specifies sign of diagonal as follows:

  • 'T' => diagonal entries are multiplied by 1 or -1 with probability .5
  • 'F' => diagonal unchanged

Not modified. 💖

🌈 GRADE 🌈

GRADE is CHARACTER*1.

Specifies grading of matrix as follows:

  • 'N' => no grading
  • 'L' => matrix premultiplied by diag( DL ) (only if matrix nonsymmetric)
  • 'R' => matrix postmultiplied by diag( DR ) (only if matrix nonsymmetric)
  • 'B' => matrix premultiplied by diag( DL ) and postmultiplied by diag( DR ) (only if matrix nonsymmetric)
  • 'S' or 'H' => matrix premultiplied by diag( DL ) and postmultiplied by diag( DL ) ('S' for symmetric, or 'H' for Hermitian)
  • 'E' => matrix premultiplied by diag( DL ) and postmultiplied by inv( diag( DL ) ) ('E' for eigenvalue invariance) (only if matrix nonsymmetric)
Note: if GRADE='E', then M must equal N.

Not modified. 🎀

🌸 DL 🌸

DL is REAL array, dimension (M).

If MODEL=0, then on entry this array specifies the diagonal entries of a diagonal matrix used as described under GRADE above. If MODEL is not zero, then DL will be set according to MODEL and CONDL, analogous to the way D is set according to MODE and COND (except there is no DMAX parameter for DL). If GRADE='E', then DL cannot have zero entries. Not referenced if GRADE = 'N' or 'R'. Changed on exit. 💜

🌸 MODEL 🌸

MODEL is INTEGER.

This specifies how the diagonal array DL is to be computed, just as MODE specifies how D is to be computed. Not modified. ✨

🌸 CONDL 🌸

CONDL is REAL.

When MODEL is not zero, this specifies the condition number of the computed DL. Not modified. 🫶

🦋 DR 🦋

DR is REAL array, dimension (N).

If MODER=0, then on entry this array specifies the diagonal entries of a diagonal matrix used as described under GRADE above. If MODER is not zero, then DR will be set according to MODER and CONDR, analogous to the way D is set according to MODE and COND (except there is no DMAX parameter for DR). Not referenced if GRADE = 'N', 'L', 'H', 'S' or 'E'. Changed on exit. 💅

🦋 MODER 🦋

MODER is INTEGER.

This specifies how the diagonal array DR is to be computed, just as MODE specifies how D is to be computed. Not modified. 🌸

🦋 CONDR 🦋

CONDR is REAL.

When MODER is not zero, this specifies the condition number of the computed DR. Not modified. 💖

👑 PIVTNG 👑

PIVTNG

  • PIVTNG (CHARACTER*1) — On entry, this bad boy specifies the pivoting permutations, and here's the tea:
    • 'N' or ' ' => none. 💅
    • 'L' => left or row pivoting (matrix must be nonsymmetric, no cap).
    • 'R' => right or column pivoting (matrix must be nonsymmetric, fr fr).
    • 'B' or 'F' => both or full pivoting, i.e., on both sides. In this case, M must equal N. 👑

If two calls to SLATMR both have full bandwidth (KL = M-1 and KU = N-1), and differ only in the PIVTNG and PACK parameters, then the matrices generated will differ only in the order of the rows and/or columns, and otherwise contain the same data. This consistency cannot be maintained with less than full bandwidth. (So like, don't try to be cute with less than full bandwidth, bestie. 😭)

  • IPIVOT (INTEGER array, dimension (N or M)) — This array specifies the permutation used. After the basic matrix is generated, the rows, columns, or both are permuted. If, say, row pivoting is selected, SLATMR starts with the last row and interchanges the M-th and IPIVOT(M)-th rows, then moves to the next-to-last row, interchanging the (M-1)-th and the IPIVOT(M-1)-th rows, and so on. In terms of , the permutation is (1 IPIVOT(1)) (2 IPIVOT(2)) ... (M IPIVOT(M)) where the rightmost cycle is applied first. This is the inverse of the effect of pivoting in LINPACK. The idea is that factoring (with pivoting) an identity matrix which has been inverse-pivoted in this way should result in a pivot vector identical to IPIVOT. Not referenced if PIVTNG = 'N'. Not modified. (So like, it's giving inverse energy, iykyk. 🔄)
  • KL (INTEGER) — On entry, specifies the lower bandwidth of the matrix. For example, KL=0 implies upper triangular, KL=1 implies upper Hessenberg, and KL at least M-1 implies the matrix is not banded. Must equal KU if matrix is symmetric. Not modified. (Lower bandwidth said "respect my range" 💅)
  • KU (INTEGER) — On entry, specifies the upper bandwidth of the matrix. For example, KU=0 implies lower triangular, KU=1 implies lower Hessenberg, and KU at least N-1 implies the matrix is not banded. Must equal KL if matrix is symmetric. Not modified. (Upper bandwidth said "anything you can do I can do better" ✨)
  • SPARSE (REAL) — On entry, specifies the sparsity of the matrix if a sparse matrix is to be generated. SPARSE should lie between 0 and 1. To generate a sparse matrix, for each matrix entry a uniform ( 0, 1 ) random number x is generated and compared to SPARSE; if x is larger the matrix entry is unchanged and if x is smaller the entry is set to zero. Thus on the average a fraction SPARSE of the entries will be set to zero. Not modified. (Sparse queen behavior, we love to see it 🍓)
  • ANORM (REAL) — On entry, specifies maximum entry of output matrix (output matrix will by multiplied by a constant so that its largest absolute entry equal ANORM) if ANORM is nonnegative. If ANORM is negative no scaling is done. Not modified. (The typo "will by multiplied" is literally iconic, don't @ me 😭)
  • PACK (CHARACTER*1) — On entry, specifies packing of the matrix as follows:
    • 'N' => no packing
    • 'U' => zero out all subdiagonal entries (if symmetric)
    • 'L' => zero out all superdiagonal entries (if symmetric)
    • 'C' => store the upper triangle columnwise (only if matrix symmetric or square upper triangular)
    • 'R' => store the lower triangle columnwise (only if matrix symmetric or square lower triangular) (same as upper half rowwise if symmetric)
    • 'B' => store the lower triangle in band storage scheme (only if matrix symmetric)
    • 'Q' => store the upper triangle in band storage scheme (only if matrix symmetric)
    • 'Z' => store the entire matrix in band storage scheme (pivoting can be provided for by using this option to store A in the trailing rows of the allocated storage)

Using these options, the various LAPACK packed and banded storage schemes can be obtained:

  • GB - use 'Z'
  • PB, SB or TB - use 'B' or 'Q'
  • PP, SP or TP - use 'C' or 'R'

If two calls to SLATMR differ only in the PACK parameter, they will generate mathematically equivalent matrices. Not modified. (Packing is an art form, okay? 🎁)

  • A (REAL array, dimension (LDA,N)) — On exit A is the desired test matrix. Only those entries of A which are significant on output will be referenced (even if A is in packed or band storage format). The 'unoccupied corners' of A in band format will be zeroed out. (Not me forgetting to zero those corners 🙈)
  • LDA (INTEGER) — On entry, LDA specifies the first dimension of A as declared in the calling program. Here's the vibe check:
    • If PACK='N', 'U' or 'L', LDA must be at least max ( 1, M ).
    • If PACK='C' or 'R', LDA must be at least 1.
    • If PACK='B', or 'Q', LDA must be MIN ( KU+1, N )
    • If PACK='Z', LDA must be at least KUU+KLL+1, where KUU = MIN ( KU, N-1 ) and KLL = MIN ( KL, M-1 )

Not modified. (LDA said "respect my dimensions" 📏)

  • IWORK (INTEGER array, dimension ( N or M)) — Workspace. Not referenced if PIVTNG = 'N'. Changed on exit. (It's giving workspace realness 🛠️)
  • INFO (INTEGER) — Error parameter on exit:
    • 0 => normal return
    • -1 => M negative or unequal to N and SYM='S' or 'H'
    • -2 => N negative
    • -3 => DIST illegal string
    • -5 => SYM illegal string
    • -7 => MODE not in range -6 to 6
    • -8 => COND less than 1.0, and MODE neither -6, 0 nor 6
    • -10 => MODE neither -6, 0 nor 6 and RSIGN illegal string
    • -11 => GRADE illegal string, or GRADE='E' and M not equal to N, or GRADE='L', 'R', 'B' or 'E' and SYM = 'S' or 'H'
    • -12 => GRADE = 'E' and DL contains zero
    • -13 => MODEL not in range -6 to 6 and GRADE= 'L', 'B', 'H', 'S' or 'E'
    • -14 => CONDL less than 1.0, GRADE='L', 'B', 'H', 'S' or 'E', and MODEL neither -6, 0 nor 6
    • -16 => MODER not in range -6 to 6 and GRADE= 'R' or 'B'
    • -17 => CONDR less than 1.0, GRADE='R' or 'B', and MODER neither -6, 0 nor 6
    • -18 => PIVTNG illegal string, or PIVTNG='B' or 'F' and M not equal to N, or PIVTNG='L' or 'R' and SYM='S' or 'H'
    • -19 => IPIVOT contains out of range number and PIVTNG not equal to 'N'
    • -20 => KL negative
    • -21 => KU negative, or SYM='S' or 'H' and KU not equal to KL
    • -22 => SPARSE not in range 0. to 1.
    • -24 => PACK illegal string, or PACK='U', 'L', 'B' or 'Q' and SYM='N', or PACK='C' and SYM='N' and either KL not equal to 0 or N not equal to M, or PACK='R' and SYM='N', and either KU not equal to 0 or N not equal to M
    • -26 => LDA too small
    • 1 => Error return from SLATM1 (computing D)
    • 2 => Cannot scale diagonal to DMAX (max. entry is 0)
    • 3 => Error return from SLATM1 (computing DL)
    • 4 => Error return from SLATM1 (computing DR)
    • 5 => ANORM is positive, but matrix constructed prior to attempting to scale it to have norm ANORM, is zero

👑 AUTHOR 👑

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

Definition at line 467 of file slatmr.f.

👑 AUTHOR 👑

Generated automatically by Doxygen for LAPACK from the source code.

And that's the tea! ☕ This page is from LAPACK Version 3.12.0, and it's the man page for slatmr.f(3). Stay slay, bestie. 💖✨

📦 where this page comes from