--- name: "dlatm3.f" section: "3" platform: "linux" package: "lapack-doc" version: "3.12.1-2" release: "Arch Linux 2026-11-01" platforms: ["linux"] url: "https://new.carta.tech/dlatm3.f" --- # dlatm3.f(3) ## NAME TESTING/MATGEN/dlatm3.f ## SYNOPSIS ### Functions/Subroutines double precision function **dlatm3** (m, n, i, j, isub, jsub, kl, ku, idist, iseed, d, igrade, dl, dr, ipvtng, iwork, sparse)\ **DLATM3** ## Function/Subroutine Documentation ### double precision function dlatm3 (integer m, integer n, integer i, integer j, integer isub, integer jsub, integer kl, integer ku, integer idist, integer, dimension( 4 ) iseed, double precision, dimension( \* ) d, integer igrade, double precision, dimension( \* ) dl, double precision, dimension( \* ) dr, integer ipvtng, integer, dimension( \* ) iwork, double precision sparse) **DLATM3** **Purpose:** ``` !> !> DLATM3 returns the (ISUB,JSUB) entry of a random matrix of !> dimension (M, N) described by the other parameters. (ISUB,JSUB) !> is the final position of the (I,J) entry after pivoting !> according to IPVTNG and IWORK. DLATM3 is called by the !> DLATMR routine in order to build random test matrices. No error !> checking on parameters is done, because this routine is called in !> a tight loop by DLATMR which has already checked the parameters. !> !> Use of DLATM3 differs from SLATM2 in the order in which the random !> number generator is called to fill in random matrix entries. !> With DLATM2, the generator is called to fill in the pivoted matrix !> columnwise. With DLATM3, the generator is called to fill in the !> matrix columnwise, after which it is pivoted. Thus, DLATM3 can !> be used to construct random matrices which differ only in their !> order of rows and/or columns. DLATM2 is used to construct band !> matrices while avoiding calling the random number generator for !> entries outside the band (and therefore generating random numbers !> in different orders for different pivot orders). !> !> The matrix whose (ISUB,JSUB) entry is returned is constructed as !> follows (this routine only computes one entry): !> !> If ISUB is outside (1..M) or JSUB is outside (1..N), return zero !> (this is convenient for generating matrices in band format). !> !> Generate a matrix A with random entries of distribution IDIST. !> !> Set the diagonal to D. !> !> Grade the matrix, if desired, from the left (by DL) and/or !> from the right (by DR or DL) as specified by IGRADE. !> !> Permute, if desired, the rows and/or columns as specified by !> IPVTNG and IWORK. !> !> Band the matrix to have lower bandwidth KL and upper !> bandwidth KU. !> !> Set random entries to zero as specified by SPARSE. !> ``` **Parameters** *M* ``` !> M is INTEGER !> Number of rows of matrix. Not modified. !> ``` *N* ``` !> N is INTEGER !> Number of columns of matrix. Not modified. !> ``` *I* ``` !> I is INTEGER !> Row of unpivoted entry to be returned. Not modified. !> ``` *J* ``` !> J is INTEGER !> Column of unpivoted entry to be returned. Not modified. !> ``` *ISUB* ``` !> ISUB is INTEGER !> Row of pivoted entry to be returned. Changed on exit. !> ``` *JSUB* ``` !> JSUB is INTEGER !> Column of pivoted entry to be returned. Changed on exit. !> ``` *KL* ``` !> KL is INTEGER !> Lower bandwidth. Not modified. !> ``` *KU* ``` !> KU is INTEGER !> Upper bandwidth. Not modified. !> ``` *IDIST* ``` !> IDIST is INTEGER !> On entry, IDIST specifies the type of distribution to be !> used to generate a random matrix . !> 1 => UNIFORM( 0, 1 ) !> 2 => UNIFORM( -1, 1 ) !> 3 => NORMAL( 0, 1 ) !> Not modified. !> ``` *ISEED* ``` !> ISEED is INTEGER array of dimension ( 4 ) !> Seed for random number generator. !> Changed on exit. !> ``` *D* ``` !> D is DOUBLE PRECISION array of dimension ( MIN( I , J ) ) !> Diagonal entries of matrix. Not modified. !> ``` *IGRADE* ``` !> IGRADE is INTEGER !> Specifies grading of matrix as follows: !> 0 => no grading !> 1 => matrix premultiplied by diag( DL ) !> 2 => matrix postmultiplied by diag( DR ) !> 3 => matrix premultiplied by diag( DL ) and !> postmultiplied by diag( DR ) !> 4 => matrix premultiplied by diag( DL ) and !> postmultiplied by inv( diag( DL ) ) !> 5 => matrix premultiplied by diag( DL ) and !> postmultiplied by diag( DL ) !> Not modified. !> ``` *DL* ``` !> DL is DOUBLE PRECISION array ( I or J, as appropriate ) !> Left scale factors for grading matrix. Not modified. !> ``` *DR* ``` !> DR is DOUBLE PRECISION array ( I or J, as appropriate ) !> Right scale factors for grading matrix. Not modified. !> ``` *IPVTNG* ``` !> IPVTNG is INTEGER !> On entry specifies pivoting permutations as follows: !> 0 => none. !> 1 => row pivoting. !> 2 => column pivoting. !> 3 => full pivoting, i.e., on both sides. !> Not modified. !> ``` *IWORK* ``` !> IWORK is INTEGER array ( I or J, as appropriate ) !> This array specifies the permutation used. The !> row (or column) originally in position K is in !> position IWORK( K ) after pivoting. !> This differs from IWORK for DLATM2. Not modified. !> ``` *SPARSE* ``` !> SPARSE is DOUBLE PRECISION between 0. and 1. !> On entry specifies the sparsity of the matrix !> if sparse matrix is to be generated. !> SPARSE should lie between 0 and 1. !> 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. !> ``` **Author** Univ. of Tennessee Univ. of California Berkeley Univ. of Colorado Denver NAG Ltd. Definition at line **223** of file **dlatm3.f**. ## Author Generated automatically by Doxygen for LAPACK from the source code.