Di -f r i hution Cat egory:Mathematics and Computers

(UC-32)

U 1 L-8O-1O5

ARGONNE NATIONAL LABORATORY9700 South Cass Avenue

Argonne, ll inois 60439

LTNPACK WORKING NOTE #13:

rMPLEMEN'rATTON i"HIDFE FOR INPACK

by

. . .1. Dongarra and C. B. Moler

OISCLAtMI -

October 1480

TABLE OF CONTENTS

Abstract ............................................

1. Tntroduction ...................................

2 . The Format .....................................

3. Overview of Tape Contents.......................

4 . LINPACK ........................................

5. Support Routings ...............................

6 . Test Aids ......................................

7. Initial Comments ...............................

8. Creating :a Library .............................

9 . Test ing ........................................

10. Listing of Subprogr -s ...

11. Card Counts for Files 1-54 ... . . . . . . . . 1?

3

5

6

6

7

7

7

8

8

8

9

5

LINPACK WORKING NOTE #13

Implementation Guide for LINPACK

by

J. J. Dongarra and C. B. Moler

ABSTRACT

This working note is intended to help a person install

and test LTNPACK. The instructions are designed for a

person whose responsibility is the maintenance of a mathe-

matical software library. We assume the reader has a

working knowledge of the system job control language and

some experience with numerical caL ulations. The installa-

tion process involves reading a magnetic tape, creating a

library from the Fortran source, then running and examining

the output of the test aids.

1. Introduction

This working note is intended to help a person install andtest LINPACK. The instructions are designed for a person whoseresponsibility is the maintenance of a mathematical softwarelibrary. We assume the reader has a working knowledge of the sys-tem job control language and some experience with numericalcalculations. The installation process involves reading a magnetictape, creating a library from the Fortran source, then running andexamining the output of the test aids.

LINPACK may be ootained from e:.ther:

National Energy Soi'tware CenterArgonne National Laboratory9700 South Cass AvenueArgonne, IL 60439(Phone: 312-972-7250)Cost: Determined for various categories of requestors

by NESC policy.or

International Mathematics and Sta;isticalLibraries, Inc.

Sixth Floor, GNP Building7500 Bellaire Rlvd.Houston, TX 77036(Phon: 713-772-1927Co-,*: i75.0C (Tape included)

The complete documentation for the package can be found in:

J. J. Dongarrv , J. . Bunch, C. B. Moler, G. W. Stewart,LINPACK Users' guide, Society for Industrial and AppliedMathematics, Philadelphia, PA, 1979.

2. The Format

LINPACK is distributed in the form of a magnetic tape whichcontains the Fortran source for LINPA,.K, the Basic Linear AlrebraSubprograms (bLAS) needed by LINPACK, the testing aids and theinitial program comments.

Tre tape contains 54 files. The usual format is 9 trackEBC_:,, unlabeled, 80 characters per logical record, 40 logicalrecords per block. A 7 track tape is available upon specialrequest.

Card counts for the 54 riles are given in section 11.

7

3. Overview of Tape Contents

There are four versions of each routine in LINPACK: real,double precision, complex and complex*16. The first three ver-sions (real., double and complex) are written in standard Fortranand are completely portable. The compl ex* 16 vera ion is provi if-dfor those compilers which allow this data type.

14. LINPACK

The first four files on the tape are:

File 1 Real LINPACK, 240 subroutines2 Doible precision " , 140 "3 Complex " , 48 "4 Complex*16 " 48 "

These four files contain the routines we call LINPACK. The re-maining 50 files contain auxiliary material.

5. Support Routines

LINPACK employs the Basic Linear Algebra Subprograms (BLAS)to carry out basic vecto.' operations. This package was designedby C. Lawson, R. Hanson, D. Kincaid and F. Krogh. Versions ofthe BLAS used in LINPACK are included in files 5-8 on the tape.The BLAS provided are written in portable Fortran and were de-signed to be as efficient as possible under these conditions.Assembly language versions of the BLAS for many machines will beavailable Fall 1979 from ACM Algorithms Distribution Service,c/o International Mathematical and ->tatistical Libraries, Inc.,and we recommend they be used. The. assembly language versionsmay have lower overhead associates with them, and therebyincrease the overall efficiency of LINPACK.

In addition to the BLAS in files 5-8 there are auxiliaryroutines which are Lused by the package or the testing routines.Subprograms CSRnF, ZDROT, and DABS1 are used by LINPACK in addi-tion to the BLA2. Functions SMACH, DMACH, CMACH, and ZMACH areused by the test drivers to calculate machine debendertparameters in the testing programs. ihese functions are used ingenerating test matrices only.

File 5 Real , 11 support subprograms6 Double precision, 117 Complex , 14 "8 Complex*16 , 15 "

To initially install, say, the real version of LINPACK, you willneed File 1 and File 5 from the tape. Each Lupport file of agiven precision contains all the routines needed to install theLINPACK routine of that same version.

8

The mac'iine parameter functions SMACH, DMACH, CMACH, and ZMACHshould be removed from the library after testing has beencompleted.

6. Test Aids

There is a collection of testing aids which should help inchecking out LINPACK after it has been installed.

Files 9-18 Test. drivers for single precision routines19-28 " " i double "29-39 " " " complex40- " " " cormplex*16

7. Initial Comments

In order to give the user some sort of online documentationfor LINPACK, we have prepared four files which contain initialprogram comments from the four versions of the code. Thesecomments describe, in general terms, what the routines do andthe meaning of the calling sequence parameters. This is notintended to be a complete discussion of what the routines can door how to use every facet of them. For this information, seethe LINPACK Users' Guide.

File 51 Single precision routines initial comments52 Double " " "t "

53 Complex "54 Cornplex*16 " "

8. Creating a Library

For the creation of the library, first you must decide whatver: *I r v1r:: n:r 2 :, ,, package you intend to install at yoursite .

To install single precision you will need file 1 and 5double 2 6complex 3 7complex * 16 4 8

We suggest you compile and create a load module library from theappropriate files.

The method of creating a library will vary from machine tomachine ana from system to system. Outlined below are twomethods which may help you in creating the library.

Some systems allow one to take many Fortran source routines,compile them at one time and send the output directly to thelinkage editor for library creation. At some IBM sites there is

9

a user written utility called ADDLINK which will do this in onestep. ADDLINK essentially calls the Fortran compiler, insertsthe appropriate linkage editor cards into the generated objectdecks and invokms the link editor. This utility is not availableon all machines, but is quite handy.

If your system does not have the ADDLINK capability, youmay have to take each subroutine, compile it and have it pro-cessed by the linkage editor on an individual basis. You willneed to separate the routines in order to do this. We have notexplicitly provided separator cards, but each subprogram startswith :,equence number "00000010" in colurins 73-80 and ends with"t END" in columns 1-9.

Separator cards can be inserted between each subroutine infiles '1-4 quite easily. The name of the subroutine can be foundin columns 18 through 22; the subroutine names are always 5characters long. The names of the subprograms in files 5-8 areharder to extract since both functions and subroutines are pro-vided there.

Once separator cards have been inserted, a utility likeIEBUPDTE on IBM machines can be used to create a library ofsource routines. This is called a partitioned dataset on IBMmachines. Once the library of source is created, each membercan there. be compiled and link edited separately to create theload library. A complete listing of the subprograms in files1-8 is given in section 10.

9. Testing

After the library is created the testing aids should be run.The testing aids are in files 9-50 of the tape and are organizedas follows:

File 9 SG File 19 DG File 29 CG File 40 ZG10 SP 20 DP 30 CP 41 ZP11 SS 21 DS 31 CS 42 ZS12 ST 22 DT 32 CH 43 ZH13 SGT 23 DGT 33 CT 44 ZT14 SCH 24 DCH 34 CGT 45 ZGT15 SUD 25 DUD 35 CCH 46 ZCH16 SEX 26 DEX 36 CUD 47 ZUD17 SQR 27 DQR 37 CEX 48 ZEX18 SSV 28 DSV 38 CQR 49 ZQR

39 CSV 50 ZSV

Each of the above test drivers test the following routines:

*G*GECO,FA,SL,DI*GBCO,FA,SL,DI

10

*POCO,FA,SL,DI*PPCO,FA,SL,DI*PBCC,FA,SL,DI

*S*SICO,FA,SL,DI*SPCO,FA,SL,DI

*H where * is S, D, C, or Z*HICO,FA,SL,DI*HPCO,FA,SL,DI

*T

*TRCO,SL,DI*GT

*GTSL*PTSL

*CH*CHDC

*EX*CHEX

*UD*CHUD,DD

*QR*QRDC,SL

*SV*SVDC

Each test file contains a main program and several subrou-tines which generate test matrices, call LINPACK subroutines andtheir support routines from the library, calculate measures ofperformance and produce output. The output unit number is set to6 by a single assignment near the beginning of the main program.There are no READ statements. An additional system dependentsupport routine called TRAPS must also be supplied.

The routines in LINPACK are designed not to overflow, causea divide by zero, or allow underflows when they would alter theresults. Underflows which are non-destructive are allowed.Some test cases are generc:ted that involve arithmetic near theunderflow and overflow limits of the machine. In order to gen-erate these test cases, underflows are necessary. On some sys-tems this may be a problem. It is necessary to provide a sub-r outine TRAPS which sets the number of arithmetic exceptionspermitted. TRAPS is taken from the WATFIV system and has the.' ::owing arguments:

THAPS(I1,I2,I3, 4,I5)

'. : ' is the number of fixed point overflows permitted..2 the number of floating point overflows permitted.

.: s the number of floating point underflows permitted.' ne number of fixed point divide by zero permitted.

. '',.e number of floating point divide by zero permitted.

11

S and D test routines have

CALL TRAPS(0,0,5001,0,0)

and C and 7 test routines have

CALL TRAP.(0,0,5001,O,3).

The subroutine TRAPS on IBM systems would include:

SUBROUTINE TRAPS(I1,I2,13,I4,I5)CALL ERRSET(208,13,-1,0)CALL ERRSET(209,I5,-1,0)

Our routine CMACH used by the complex test routines, gen-erates a large number for the machine on which it is running.It does this by taking the reciprocal of a small number. Thismay result in a division by zero if the compiler is not perform-ing complex division correctly. Consequently the complex testsmay generate one or more divisions by zero.

All the routines in the package have passed through the BellLaboratories' PFORT Checker, which verifies the codes conform toa Fortran ANSI subset. The routines have also been run on thenew WATFIV compiler, but will not run on the old WATFIV becauseof the way dummy arrays are declared.

Each of the different test routines produces output whichsummarizes how well the routines handled the problem. Figures ofmerit in the form of ratios are printed out and the suspiciousones are flagged.

For test paths SG, SP, SS, ST, and SGT (and their doubleprecision and complex counterparts), the measures are:

COND is the ratio of the estimate of the condition number toACTUAL the actual condition number, which is calculated ex-

plicitly. If this number is > 1, then something iswrong.

ACTUAL is the reciprocal of the previous measure. This isCOND almost always < 10, but there is no known upper bound

on its possible value.

ERROR is f O , where x is the true solution, x is theE. COND X

computed solution, e is the machine rounding unit, andCOND is the estimate of the condition number of thematrix.

ERROR-T is the measure as above for solving A Tx = b.E*COND X

12

RESID is Ax-bRESID is , where A is the original matrix, x is the

computed solution, b is the right hand side, and c isthe machine rounding unit.

R1I1D-T is the measure as above for solving A Tx = b.

A-LU is A-LU , where A is the original matrix, L and U areEA - produced by the decomposition, and E is the machine

rounding unit.

AA 1 -IA*AI-I is ' COND , where A is the original matrix, A- 1 is theEVCOND computed inverse of A, I is the identity matrix, : Cs

the machine rounding unit, and COND is the estimate ofthe condition of A.

If any of the last six ratios are > N, the order of the matrix,then they are considered suspicious and are flagged as such.

For the test path SSV, the measures are:

U*SIGMA*VH is X -X , where X is the original matrix, U,

and V are produced by the decomposition, andis the machine rounding unit.

UHU is , where U is a matrix produced by thedecomposition, I is the identity, and E is themachine rounding unit.

VHV is VHV- , where V is a matrix produced by thedecomposition, I is the identity matrix, and L

is the machine rounding unit.

:f any of these ratios are > 100, then they are considered sus-picious and are flagged as such.

For the test path SQR, the measures are:

D MULTIPLICATION is -QX, where R and Q are produced

by the decomposition, X is the originalmatrix, and f is the machine roundingunit.

-7 7IPLICATION is X , where X is the original

matrix, Q and P are produced by thedecomposition, and is the machinerounding unit.

13

If any of these ratios are > 100, then they are considered sus-picious and are flagged as such.

The three test paths SCH, SEX, 'ID produce similar ratios,but no attempt is made to flag partic 'alues as suspicious.

The machine rounding unit, which approximate distancefrom 1.0 to the next floating point nus. is calculated by sub-routines SMACH, DMACH, CMACH, and ZMACH. These routines alsocompute a small and large number for the machine on which theyare running. The small number is roughly the underflow limitdivided by the machine rounding unit and the large number is thereciprocal of that.

These tests are fairly stringent and so the appearance of afew "slightly" suspicious ratios should not be cause for alarm.Improper installation or errors in compilers and operating sys-tems cause the test runs to terminate abnormally or produce manyvery large ratios.

Each test driver produces at most 600 lines of output. Thetime to run each test, including both compilation and eA-ecution,is given by the table below.

IBM 370/195, CDC 7600 15 secondsIBM 370/168, CDC 6600 1 minuteIBM 360/75, UNIVAC 1110, Honeywell 6020 4 minutes

These times are only rough estimates and have not been gen-erated from actual runs but from extrapolations.

14

10. List of Subprogram:;

LINPACK Subroutines

File 1 rile 2 File 3 File 4

SGECOSGEFASGESLSGED 1SGBCOSGBFASG LSGBDISPOCOSPOFASPOSLSPC DISPPCOSIPPF ASPPS LSPIPDISPPCOSPBFAS PHS1LSP DISICc)SS1FASSISLSSIDISSPCOSSPFASSPSLS S P D)1STHCOST HSLSTHBISGTI.iSPT SLSCHDCSCHUDSC1 DDSCHEXSQRDCSQHSLssVDC

DGECODGEFADGE.L1DG ED )DGC 0DGEADGB LDG 1)1DPOC ODPOFADPOSLDPODIDPPCOD PP F ADPPSLDPPDIDPBCODP13 FADPBSLDP B3D IDS ICODS1F ADSISLDSIDIDSP CODSPFADSPSLDSPDIDTHCODTHS LDTHDIDGTSL1)PTSLDCBDCDC If IDDC HPD UDC IE XDQHDCDQ HS LDSV DC

CG E COCGEFAC G E S LCGEDICGPCOCGBFACG B S LCG D ICPUCOCPCFACPOSLCPODICPPCOCPPFACPPSLCPPDICPBCOCP13FACPBS1LCPIBD ICSICOCSIFACSISLCSIDICSPCOCSPFACSPS1LCSPDICHICOCHI FACHISL,C H I D ICHPCOCHPFACHPS[.CHPDICTHCOCTHSLCTRDICGTSLCPTSI.CCHDCCCHU )CC 2 D1)CCHI;XCQHDCCQRSLCSVDC

ZGECOZGEFAZGESLZGEDIZGIBCOZGHFA

ZGBSLDZGBDI

ZPOCOZP0FAZP 0SLZPODIZPPCOZPPFAZ P P S LZPPDIZPBCOZPbFAZP1B SLZP DIZSICOZSIFAZSISLZSIDIZSPCOZSPFAZSPSLZSPDIZHICo

ZHIFA

ZHISLZHIDIZHPC0Z HP F AZHSLZHPDIZTHCOZTHSLZT8)HIZGTSLZP1 SLZCHDCZCHUDZCHDDZCHEXZORDCzQ PSL.ZSVDC

15

Support Subprograms

File 5 File 6 File 7 File 8

ISAMAX DASUM CAXPY DABS1SASUM DAXIY CCOPY DROTGSAXPY DCOPY CDOTC DZASUMSCOPY DDOT CDOTU DZtJRM2SDOT DMACH CMACH ZDHOTSMACH DNRM2 CHOTU T ZAMAXSNHM2 DROT CSCAL ZAXPYSHOT DHOTG CSPOT ZCOPYSROTG DSCAL CSSCAL ZDOTCSSCAL DSWAP CSI'AP ZLCTUSSWAP IDAMAX ICAMAX ZDSCAL

SCASUM ZMACHSCNNM2 ZHOTGSROTG ZSCAL

ZSWAP

Not.e: Routine SROTG appears in both file 5 and file 7 androutine DROTG appears in both file 6 and file 8.

lph._beLical List. of :;iubprogrimnin Files 1 throurh F

CAXI'Y CSIFA UPTSL SH1IM2 ZGBCLCCHDC CSISL DO IDC SPeCU ZGe.COCCHDD CSPCO DQhSL SPIADI ZGEDICCHEX CSDPI DROT SPPFA ZGFACCHUD CSPFA I)ItOTG SP8.1I. ZGt:SLCCoPY C;PS. DSCAL SPOCO ZGTSLCDOTC CS ROT DSICO SPODI ZHICOCDOTU CSSCAL DSIuI SPOFA zI!IDICGHCO CSV1C DSIFA SPOS Z!I'rACGHDI CSWAP DSISL SPPCO ZHISLCGiFA CTHCO D PCO SPP N ZHPCOCGBE CTHDI DSPDI SePFA ZHPDICGECO CTPSL VSPFA fPPL ZIPFACGEhDI :A BiS 1 DSP:SL SPT';L ZIIPSLCGEFA DASUM DSVDC ,QHDC ZMACHCGESL D)AXPY KSWAP :;QSL ZPHCuCGT:SL DCHDC DTHCO hOT ZPF:uICiH ICo DCHDD DUHD1 SHOT ZPVFACHIDI DCHEX DTFRSL SSCAL ZPiZLCHI FA DCIfUD DZ A:;UM S I Cu ZPOCOCHISL COPY IZ1JfNM? : IDI ZPODICIIPC0 DDOT ICAMAX SSIFA ZPOFAC11POI DGHC( IDA11AX BS1S L ZPOSLCHPFA DGI!D I ISAMAX SSPC0 ZPPCOCIIP1'L )GiPiA IZAMAX SSPLI ZPPDICHACII DGG:;L SASUM c;SIPFA ZPHr ACP13C1 DGECO SAXPY SSP:;1. ZPPSLCPIDI DGEPI SCASUM SSVIC ZPT:LCP A DG EFA SCIiIDC S6WAi ZOhDCCPD+SL DGESL SCHDD STH(C) ZQhSLCPOCu DGTSL SCH1;X ST id1 /.HOTGCPODI DMACH SCHU1) STHSL ZSCALCPOFA DNJHM2 SCNPM? ZAXPY ZSICOCPOSL DPPCO SCoPY ZCHIDC ZSIDICPICO DPPDI SOT ZCII0b ZSIFACPPDI DPIBFA SGi+' 0 7Cl0X ZSISLCPPFA bP 31[ SG'D I Z(HU11 ZSPCOCPFS. DPOCo SGP1-A ZCO1i ZSPDICPTS. DPODI SC;. ZDO1TC ZSP ACQHDC DPOFA SGtC) ZDOTU ZSKPLCQH:;1L 1d0:,1. SGKDI ZUhOT ZSVDCCROTG DPPCO SCE.FA 7IDSC.L .SWAPCSCAL DPPDI SGESL ZGFCo ZTCOCSIC( DPfPE A SGTSL. ZGHDI ITHDIC:1D1 DPPSL SMACK ZG14FA ZTHSL

11. Card Counts for Files 1-54

contains 6,861

6,867

8,771

8,935

cards

less than

2,

2,

3,

3,

700 cards each

708

714

189

18)

17

File 1

2

34

5-50

51

52

53

54

18

Internal:

J. J. Dongarra (20) G. W. PieperG. T. Garvey R. J. RoystonA. g. Krisciunas National Energy Software Center (100)P. C. Messina ANL Contract FileD. M. Pahis ANL LibrariesL. M. Fhebus (2) TIS Files (6)

External:

DOE-TIC, for distribution per UC-32 (183)Manager, Chicago Operations and Regional Offinge, DOE-COROChief, ')l'f'ice of Patent Counsel., DOE-COROPresident, Argonne Universities AssociationApplied Mathematics Division Review Committee:

;. Estrin, J. California, Los AngelesW. M. Gentleman, 1J. Waterloo.1. M. Ortega, U. VirginiaK. N. Pinson, Bell Telephone Labs5. Rosen, Purdue 1J.M. F. Wheeler, Rice TI.D. M. Young, Jr., U. Texas at Austin

international Mithernat ical. arid Statistical Libraries (100)