TESTING/MATGEN/dlatme.f(3)

📦
version 3.12.1 · 3 versions
, in arch rolling

🎀 NAME 🎀

okay so this is TESTING/MATGEN/dlatme.f from the Library Functions Manual — the DLATME page, bestie. bestie listen, it’s giving test-matrix main character energy and we’re gonna get through every single detail, no cap. 💅

✨ SYNOPSIS ✨

✨ Functions/Subroutines ✨

       subroutine dlatme (n, dist, iseed, d, mode, cond, dmax, ei, rsign,
           upper, sim, ds, modes, conds, kl, ku, anorm, a, lda, work, info)
           DLATME

🌈 Function/Subroutine Documentation 🌈

okay here’s the full typed signature, exactly as it appears — no renaming, no merging, no invented options, periodt:

   subroutine dlatme (integer n, character dist, integer, dimension( 4 ) iseed,
       double precision, dimension( * ) d, integer mode, double precision cond,
       double precision dmax, character, dimension( * ) ei, character rsign,
       character upper, character sim, double precision, dimension( * ) ds,
       integer modes, double precision conds, integer kl, integer ku, double
       precision anorm, double precision, dimension( lda, * ) a, integer lda,
       double precision, dimension( * ) work, integer info)
       DLATME

🦋 Purpose 🦋

DLATME generates random non-symmetric square matrices with specified eigenvalues for testing LAPACK programs. main character energy, honestly.

It operates by applying this exact sequence of operations:

  1. Set the diagonal to D, where D may be input or computed according to MODE, COND, DMAX, and RSIGN as described below. 🫶
  2. If complex conjugate pairs are desired (MODE=0 and EI(1)='R', or MODE=5), certain pairs of adjacent elements of D are interpreted as the real and complex parts of a complex conjugate pair; A thus becomes block diagonal, with 1x1 and 2x2 blocks. 💅
  3. If UPPER='T', the upper triangle of A is set to random values out of distribution DIST. 🌸
  4. If SIM='T', A is multiplied on the left by a random matrix X, whose singular values are specified by DS, MODES, and CONDS, and on the right by X inverse. 🔥
  5. If KL < N-1, the lower bandwidth is reduced to KL using Householder transformations. If KU < N-1, the upper bandwidth is reduced to KU. ⭐
  6. If ANORM is not negative, the matrix is scaled to have maximum-element-norm ANORM. 🦋
Note: since the matrix cannot be reduced beyond Hessenberg form, no packing options are available. 👀

🍓 Parameters 🍓

okay bestie, here’s every parameter in order, no skips, fr fr:

N

N is INTEGER. It’s the number of columns (or rows) of A. Not modified. 💖

DIST

DIST is CHARACTER*1. On entry, DIST specifies the type of distribution to be used to generate the random eigen-/singular values, and for the upper triangle (see UPPER). The values are:

  • '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 DLATME to continue the same random number sequence. Changed on exit. 🎀

D

D is DOUBLE PRECISION array, dimension ( N ). This array is used to specify the eigenvalues of A. If MODE=0, then D is assumed to contain the eigenvalues (but see the description of EI), otherwise they will be computed according to MODE, COND, DMAX, and RSIGN and placed in D. Modified if MODE is nonzero. 💜

MODE

MODE is INTEGER. On entry this describes how the eigenvalues are to be specified:

  • MODE = 0 means use D (with EI) 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. Each odd-even pair of elements will be either used as two real eigenvalues or as the real and imaginary part of a complex conjugate pair of eigenvalues; the choice of which is done is random, with 50-50 probability, for each pair.
  • 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 between 1 and 4, D has entries ranging from 1 to 1/COND, if between -1 and -4, D has entries ranging from 1/COND to 1. Not modified. 💅

COND

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

DMAX

DMAX is DOUBLE PRECISION. If MODE is neither -6, 0 nor 6, the contents of D, as computed according to MODE and COND, will be scaled by DMAX / max(abs(D(i))). Note that DMAX need not be positive: if DMAX is negative (or zero), D will be scaled by a negative number (or zero). Not modified. 🫶

EI

EI is CHARACTER*1 array, dimension ( N ). If MODE is 0, and EI(1) is not ' ' (space character), this array specifies which elements of D (on input) are real eigenvalues and which are the real and imaginary parts of a complex conjugate pair of eigenvalues. The elements of EI may then only have the values 'R' and 'I'. If EI(j)='R' and EI(j+1)='I', then the j-th eigenvalue is CMPLX( D(j) , D(j+1) ), and the (j+1)-th is the complex conjugate thereof. If EI(j)=EI(j+1)='R', then the j-th eigenvalue is D(j) (i.e., real). EI(1) may not be 'I', nor may two adjacent elements of EI both have the value 'I'. If MODE is not 0, then EI is ignored. If MODE is 0 and EI(1)=' ', then the eigenvalues will all be real. Not modified. 🦋

RSIGN

RSIGN is CHARACTER*1. If MODE is not 0, 6, or -6, and RSIGN='T', then the elements of D, as computed according to MODE and COND, will be multiplied by a random sign (+1 or -1). If RSIGN='F', they will not be. RSIGN may only have the values 'T' or 'F'. Not modified. 🌸

UPPER

UPPER is CHARACTER*1. If UPPER='T', then the elements of A above the diagonal (and above the 2x2 diagonal blocks, if A has complex eigenvalues) will be set to random numbers out of DIST. If UPPER='F', they will not be. UPPER may only have the values 'T' or 'F'. Not modified. 🔥

SIM

SIM is CHARACTER*1. If SIM='T', then A will be operated on by a , i.e., multiplied on the left by a matrix X and on the right by X inverse. X = U S V, where U and V are random unitary matrices and S is a (diagonal) matrix of singular values specified by DS, MODES, and CONDS. If SIM='F', then A will not be transformed. Not modified. ⭐

DS

DS is DOUBLE PRECISION array, dimension ( N ). This array is used to specify the singular values of X, in the same way that D specifies the eigenvalues of A. If MODE=0, the DS contains the singular values, which may not be zero. Modified if MODE is nonzero. 💖

MODES

MODES is INTEGER. ✨

CONDS

CONDS is DOUBLE PRECISION. Same as MODE and COND, but for specifying the diagonal of S. MODES=-6 and +6 are not allowed (since they would result in randomly ill-conditioned eigenvalues.) 👑

KL

KL is INTEGER. This specifies the lower bandwidth of the matrix. KL=1 specifies upper Hessenberg form. If KL is at least N-1, then A will have full lower bandwidth. KL must be at least 1. Not modified. 🌈

KU

KU is INTEGER. This specifies the upper bandwidth of the matrix. KU=1 specifies lower Hessenberg form. If KU is at least N-1, then A will have full upper bandwidth; if KU and KL are both at least N-1, then A will be dense. Only one of KU and KL may be less than N-1. KU must be at least 1. Not modified. 🍓

ANORM

ANORM is DOUBLE PRECISION. If ANORM is not negative, then A will be scaled by a non-negative real number to make the maximum-element-norm of A to be ANORM. Not modified. 🧚

A

A is DOUBLE PRECISION array, dimension ( LDA, N ). On exit A is the desired test matrix. Modified. 💜

LDA

  • LDA — an INTEGER, and it's literally just the first dimension of A exactly as you declared it back in the calling program. Rule: LDA must be at least N. And good news — it does not get modified. Your girl stays untouched. 💅
  • WORK — a DOUBLE PRECISION array, dimension ( 3*N ). It's the workspace, aka the little backstage area where the messy stuff happens. Heads up: this one does get modified. 🛠️
  • INFO — an INTEGER, the error code. On exit, INFO gets set to one of these values, and bestie you're gonna wanna screenshot this list because it's giving "final exam cheat sheet" energy:
    • 0 => normal return ✨
    • -1 => N negative
    • -2 => DIST illegal string
    • -5 => MODE not in range -6 to 6
    • -6 => COND less than 1.0, and MODE neither -6, 0 nor 6
    • -8 => EI(1) is not ' ' or 'R', EI(j) is not 'R' or 'I', or two adjacent elements of EI are 'I'.
    • -9 => RSIGN is not 'T' or 'F'
    • -10 => UPPER is not 'T' or 'F'
    • -11 => SIM is not 'T' or 'F'
    • -12 => MODES=0 and DS has a zero singular value.
    • -13 => MODES is not in the range -5 to 5.
    • -14 => MODES is nonzero and CONDS is less than 1.
    • -15 => KL is less than 1.
    • -16 => KU is less than 1, or KL and KU are both less than N-1.
    • -19 => LDA is less than N.
    • 1 => error return from DLATM1 (computing D) 😭
    • 2 => cannot scale to DMAX (max. eigenvalue is 0) 💀
    • 3 => error return from DLATM1 (computing DS)
    • 4 => error return from DLARGE
    • 5 => zero singular value from DLATM1.
Ok so real talk: any negative INFO means you passed something cursed. Any positive INFO means something went sideways deeper in the stack. Either way, don't panic — just read the number and trace it back. You got this. 🫶

👑 Author

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

Definition at line 327 of file dlatme.f.

🧚 Author

Generated automatically by Doxygen for LAPACK from the source code.

And that's a wrap on dlatme! 🌈 This whole glow-up came to you courtesy of LAPACK, Version 3.12.0, and the page is dated in the footer along with the source file TESTING/MATGEN/dlatme.f(3). Go forth and generate some matrices, bestie — you're literally the main character of linear algebra now. 💖🎀🦋

📦 where this page comes from