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

💖 NAME 💖

okay bestie, this is the manual page for /home/abui...N/slatms.f(3) — and the actual file it documents is /home/abuild/rpmbuild/BUILD/lapack-static-3.12.0-build/lapack-3.12.0/TESTING/MATGEN/slatms.f. We're in LAPACK test-matrix territory, and it's giving random matrices with specified singular values energy. 💅

✨ SYNOPSIS ✨

🧚 Functions/Subroutines 🧚

       subroutine SLATMS (m, n, dist, iseed, sym, d, mode, cond, dmax, kl, ku,
           pack, a, lda, work, info)
           SLATMS

🦋 Function/Subroutine Documentation 🦋

   subroutine SLATMS (integer m, integer n, character dist, integer, dimension(
       4 ) iseed, character sym, real, dimension( * ) d, integer mode, real
       cond, real dmax, integer kl, integer ku, character pack, real,
       dimension( lda, * ) a, integer lda, real, dimension( * ) work, integer
       info)

SLATMS

🎯 Purpose 🎯

okay so SLATMS generates random matrices with specified singular values (or symmetric/hermitian matrices with specified eigenvalues) for testing LAPACK programs. It's literally a matrix-making machine for tests, no cap. ✨

SLATMS operates by applying the following sequence of operations:

Set the diagonal to D, where D may be input or computed according to MODE, COND, DMAX, and SYM as described below.
Generate a matrix with the appropriate band structure, by one of two methods:

🌸 Method A 🌸

Generate a dense M x N matrix by multiplying D on the left and the right by random unitary matrices, then reduce the bandwidth according to KL and KU, using Householder transformations.

🌸 Method B 🌸

Convert the bandwidth-0 (i.e., diagonal) matrix to a bandwidth-1 matrix using Givens rotations, out-of-band elements back, much as in QR; then convert the bandwidth-1 to a bandwidth-2 matrix, etc. Note that for reasonably small bandwidths (relative to M and N) this requires less storage, as a dense matrix is not generated. Also, for symmetric matrices, only one triangle is generated.

Method A is chosen if the bandwidth is a large fraction of the order of the matrix, and LDA is at least M (so a dense matrix can be stored.) Method B is chosen if the bandwidth is small (< 1/2 N for symmetric, < .3 N+M for non-symmetric), or LDA is less than M and not less than the bandwidth.

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 upper triangular)
store the lower half columnwise (if symmetric or lower triangular)
store the lower triangle in banded format (if symmetric or lower triangular)
store the upper triangle in banded format (if symmetric or upper triangular)
store the entire matrix in banded format

If Method B is chosen, and band format is specified, then the matrix will be generated in the band format, so no repacking will be necessary.

💅 Parameters 💅

🌟 M 🌟

M is INTEGER. The number of rows of A. Not modified.

🌟 N 🌟

N is INTEGER. The 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 the random eigen-/singular values:

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

🌟 SYM 🌟

SYM is CHARACTER*1.

If SYM='S' or 'H', the generated matrix is symmetric, with eigenvalues specified by D, COND, MODE, and DMAX; they may be positive, negative, or zero.

If SYM='P', the generated matrix is symmetric, with eigenvalues (= singular values) specified by D, COND, MODE, and DMAX; they will not be negative.

If SYM='N', the generated matrix is nonsymmetric, with singular values specified by D, COND, MODE, and DMAX; they will not be negative.

Not modified.

🌟 D 🌟

D is REAL array, dimension ( MIN( M , N ) ). This array is used to specify the singular values or eigenvalues of A (see SYM, above.) If MODE=0, then D is assumed to contain the singular/eigenvalues, otherwise they will be computed according to MODE, COND, and DMAX, and placed in D. Modified if MODE is nonzero.

🌟 MODE 🌟

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

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 sets D to random numbers from the 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.

If SYM='S' or 'H', and MODE is neither 0, 6, nor -6, then the elements of D will also be multiplied by a random sign (i.e., +1 or -1.)

Not modified.

🌟 COND 🌟

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

🌟 DMAX 🌟

DMAX is REAL. 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))); thus, the maximum absolute eigen- or singular value (which is to say the norm) will be abs(DMAX). 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.

🌟 KL 🌟

KL is INTEGER. This specifies the lower bandwidth of the matrix. For example, KL=0 implies upper triangular, KL=1 implies upper Hessenberg, and KL being at least M-1 means that the matrix has full lower bandwidth. KL must equal KU if the matrix is symmetric. Not modified.

🌟 KU 🌟

KU is INTEGER. This specifies the upper bandwidth of the matrix. For example, KU=0 implies lower triangular, KU=1 implies lower Hessenberg, and KU being at least N-1 means that the matrix has full upper bandwidth. KL must equal KU if the matrix is symmetric. Not modified.

🌟 PACK 🌟

PACK is CHARACTER*1. This specifies packing of 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 the matrix is symmetric or upper triangular)
'R' => store the lower triangle columnwise (only if the matrix is symmetric or lower triangular)
'B' => store the lower triangle in band storage scheme (only if matrix symmetric or lower triangular)
'Q' => store the upper triangle in band storage scheme (only if matrix symmetric or upper triangular)
'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 SLATMS differ only in the PACK parameter, they will generate mathematically equivalent matrices. Not modified.

🌟 A 🌟

...and now the moment you've all been waiting for — the actual argument tea ☕️ buckle up bestie, this is the part where every single detail matters 💅

A — a REAL array, dimension ( LDA, N ). On exit, A is the desired test matrix ✨ and here's the whole glow-up: A gets generated first in full (unpacked) form, and then packed — but only if PACK says so. So the first M elements of the first N columns will always be modified. If PACK specifies a packed or banded storage scheme, then all LDA elements of the first N columns get modified, and any elements that don't correspond to elements of the generated matrix are set to zero 🫶. Modified.
LDA — an INTEGER. It's the first dimension of A as declared in the calling program, iykyk. If PACK='N', 'U', 'L', 'C', or 'R', then LDA must be at least M. If PACK='B' or 'Q', then LDA must be at least MIN( KL, M-1) (which equals MIN(KU,N-1) — same thing, different wig 💁‍♀️). If PACK='Z', LDA must be big enough to hold the packed array: MIN( KU, N-1) + MIN( KL, M-1) + 1. Not modified.
WORK — a REAL array, dimension ( 3*MAX( N , M ) ). It's the workspace, the little backstage area where the magic happens 🎀. Modified.
INFO — an INTEGER, the error code. On exit, INFO is set to one of these icons:
- 0 => normal return, we ate and left no crumbs 👑
- -1 => M is negative, or M is unequal to N and SYM='S', 'H', or 'P'
- -2 => N is negative
- -3 => DIST is an illegal string
- -5 => SYM is an illegal string
- -7 => MODE is not in range -6 to 6
- -8 => COND is less than 1.0, and MODE is neither -6, 0 nor 6
- -10 => KL is negative
- -11 => KU is negative, or SYM='S' or 'H' and KU is not equal to KL
- -12 => PACK is an illegal string, or PACK='U' or 'L' and SYM='N'; or PACK='C' or 'Q' and SYM='N' and KL is not zero; or PACK='R' or 'B' and SYM='N' and KU is not zero; or PACK='U', 'L', 'C', 'R', 'B', or 'Q', and M is not N.
- -14 => LDA is less than M, or PACK='Z' and LDA is less than MIN(KU,N-1) + MIN(KL,M-1) + 1
- 1 => error return from SLATM1 😭
- 2 => cannot scale to DMAX (max. sing. value is 0) 💀
- 3 => error return from SLAGGE or SLAGSY

bestie fr fr, if you see a negative INFO it's giving "u passed me something cursed" — check your args before you come for the routine 🙈

👑 Author 👑

The absolute icons who brought you this:

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

📍 Definition at line

319 of file slatms.f. Not modified, not up for debate 💅

👑 Author (yes, again, she contains multitudes) 👑

Generated automatically by Doxygen for LAPACK from the source code. So like, don't come for the formatting, a robot did it and honestly she slayed ✨

and that's the whole page babes 🫶 this was LAPACK Version 3.12.0, straight out of /home/abui...N/slatms.f(3) — go forth, generate those test matrices, and remember: the first M elements of the first N columns will be modified. periodt. 💖🎀🦋

📦 where this page comes from

opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
opensuse-leap 16.0: lapack-man 3.12.0-160000.2.2 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms