AMT

DAP Series

General Support

GSLIB

(man010.02)

i

AMT endeavours to ensure that the information in this doc- ument is correct, but does not accept responsibility for any error or omission.

Any procedure described in this document for operating AMT equipment should be read and understood by the operator before the equipment is used. To ensure that AMT equipment functions without risk to safety or health, such procedures should be strictly observed by the operator.

The development of AMT products and services is continuous and published information may not be up to date. Any partic. ular issue of a product may contain part only of the facilities described in this document or may contain facilities not de- scribed here. It is important to check the current position with AMT.

Specifications and statements as to performance in this docu- ment are AMT estimates intended for general guidance. They may require adjustment in particular circumstances and are therefore not formal offers or undertakings.

Statements in this document are not part of a contract or program product licence save in so far as they are incorporated into a contract or licence by express reference. Issue of this document does not entitle the recipient to access to or use of the products described, and such access or use may be subject to separate contracts or licences.

Technical publication man010.02

First edition 20 October 1987 Second edition 22 April 1988

Copyright © 1988 by Active Memory Technology

Publications Manager

Active Memory Technology Ltd 65 Suttons Park Avenue Reading

Berks, RG6 1AZ, UK

Tel: 0734 661111

man0g10.02

No part of this publication may be reproduced in any form without written permission from Active Memory Technology.

AMT will be pleased to receive readers’ views on the contents, organisation, etc of this publication. Please make contact at either of the addresses below:

Publications Manager

Active Memory Technology Inc 16802 Aston St Suite 103 Irvine

California, 92714, USA

Tel: (714) 261 8901

AMT

Contents

1 Introduction

1-1. Background: 3.04 spas eres os Aw owe ho AE ee el vues oo Bois Weld as 1.2 Arrangement of Documentation. ........0.0.0.0 000.0000. eee eee 133: “Validation co. i036 se. ore Shae Sohne £5 OLR od OR ees A gens Gite Gs 1A. Pull-form. Deetumentation. i... 4.x hn¥ 6 ee o So, A pk RG ee SEAS 14.1" “Purpose:¢ se oie a Gasaeven Gala ace aoe Sb oe wal dled a bees Ge Lea2 - SPOCIICANON «ow. eee SS Os erie de BAL Se oe a a Og wR Tas Deseripuone Ss. 2s ese ak a nbs Sk S oe bm be ws, 4 oe ee ae De Bs ep TAA? = ETONCER inc oa) du i eden sot, Chey eon, 6 cae Sar te Be he oe ek ded cArpuments 5") sees Gow & ee gelan ts DG eee Se bok MAG ee Gels PAG. ~Ereor- Indicators: c)45 eke EEE OE SoG eae ea eR pd 14.7 Auxiliary routines 2... 2... L408. > ACCULACY® fics 8.x Sean thik, dy Sy aoa eed hn BE a he ites ed Won fb ee Lao. Kercher Comments: i. sigue ates tO Ge eS eee BS Wate lend to dh we dae 1.4,10+ Keywords: s 6 ete) fee Soin Seas dk A ead Aer a ace Wee aS Gad 14.11 Examples. soos ewok a warts Se Sab ee Oa, ee eh bo Paes 1.5 Access tothe Library. 2... 0... ee ee eee 1.5.1 Using the library under UNIX ..................0.00004 1.5.2 Using the library under VAX/VMS............2.....0..00.0. 1.6 Other AMT subroutine libraries... .........0.0.00200000 000000 eae

General Support library ~ _man010.02

ill

CONTENTS CONTENTS 2 GSLIB quick-reference catalogue 5 3 A03 Variable precision arithmetic 15

od POS ADDIPLANEGIU So oc¢ Sow 4 oleae) 8 Ae ee eel as bn 16 4 C06 Summation of series 19 Bok COG IB iis WOO: Aa ete ob gatancepae ath ng ek Sle ae te. ewe tee ed 20 es ONG SRE TY care desea. ois Qi aeses Ate Gael Maal HE tect tes Geet en TS de Rie: A 24 5 FO1 Matrix Operations 29 OM: aack canigs pe Ae ae ele lee agg ae Sa kt he det g Andee dos Jam 30 Dee OL MIN pias ee ace ta By dein hand Beh Seda tat Sot Bn, we ile cau, a te OS 34 bio” POLSMM.STRASSEN. o.6. icfj. Bogan ere ie kw Se wre bee be ict dee thas 37 6 F02 ~ Eigenvalues and eigenvectors 41 6.1 FO2.ALL.EIG-VALS_TD_ES .............. tt Rept ates ashen a? ats 42 6.2 FO2.ALL.EIG_VALS.TD_LV......0.0.000.0 00000000 en Planet 2 46 G3 --BO2 BIG LVALSSTDILY 2 55 oo d's ak wth ds, eB ae eee Roe Re 50 Cod HORTA CODE ie: tate ee ah ae wae fa dic sess fas Beth gp che Mains Mee Sapo Lae bd a 54 7 F04 Simultaneous linear equations 59 fol POP BIGSOLY Beas cise, a dee aa teles @ Oo eeieiwuinnd o tile bd Dw Beak 60 Ged ROCESS Woy seG race tints Cate Ge RNa Baie ta, Beem slnon Bie ie die HAs eas Ad 66 73 FO4.QR.GIVENS_SOLVE ....00 000 cc eee eee eee ee een en 71 Woe | OAS ERIDS LES: Slee itch oe cs oy: dena he ehuidte, Bait Sele NG eck ee Be oe 75 (9. FO4. PRIDS E5250) «ih odo no wh ee adn WAS De Gh eo Ae d Ake eS 78 Uo MOR VRID GY? 5, 3 poe ateda ial lawke seek. Ge Be an, td eh ood dn EMA de. é 82 8 G05 ~ Random numbers 85 Bab” Gob. MCL BEGIN. 4.45 ¢ Wow ate oe RRS RAS wet Faraone Mle 86 ine? MASAO LG: fe fe 3d a tay Sk ge dente tg Fy in dS Hoke, MAS Gad at Doak ea Mele deena oes 88

iv man010.02 AMT

CONTENTS CONTENTS

813. GOS 2M OC LIB ih ta cout BB ts ose anid Sas be nue sted bo Se Dee Bh Pde ace 90 8.4 GO05.MC_NORMAL_R4. 2... 2. 92 8:5 (GO5YMCLRA® vee he ee ek Gs ae ee eee ek ee a Ee 94 S605 .MCLRS cet a7 AE a HG ae hy ERE Aes Boe ed Be Behe wy a 96 8.7 GO5.MC_REPEAT. 2... 2... ee ee es 98

9 HO1 Operations research, graph structures, networks 101 9.1. HOLL ASSIGN: 34 ea, Sabb Oe ek Pe oe RE RAO SD 8 102 10 J06 Plotting 107 10.1 JOOLCHAR.CONT .. 2... 0... 2. ee 108 102 J OOZE BRA CHART 5.6% .02.5.5 Briefe Sue bo 4 dd mene. swe BM SEG bY 111 11 M01 - Sorting 113 PA MG) BSORT-LY 2 Adie simaueety es Gk asd Fee Gin eater atr td an Gh 114 112; MOLZINV-PERMULTEcCOLS > 4:2 ste eee SAAN oe a we RL 117 ) 1L3 MOLZINVOPERMUTE JLVi32 oc. i sees oa el ee hho ee ee 121 11:4: MOLLINV=PERMUTE..ROWS 54 2 26:04. 2 hi wwewew ek bd Bee aE Ss 124 £15: MOL PERMUTE COLS ine oo ee el Re Rte eee atl ae 128 11.66 MO1.PERMUTE.LV.32 ................, Sergi dy alan hy Sahew Ba jalea-e aoe 2 132 117 MOL Ss PERMUPEWROWS 3:5 s.0 eS ee ale Be dnt ee ee EE ER 135 FL Be WOT SORA UA ce Sere sata 2 Sty es, Poth Sh ae Ries ek wea eve Sk 139 TL MOLSORTV. Ree a ate rina dade ne Od ae eile inane wera 142 12 S Special functions ; 147 PZ SOLAR COS 2 Gre 6 spite oak Sth Whe he de, pe We hak ae a, tl te tare, wha one 148 12:2; S04, RRC OS EN ee en wicks we Ge yi oe kg Eg Suelo 9 aed BE SRY Ok ed OOS 152 M2 UE OL INDE i ea a WI oN Gane ik at etcge eee en SO East Ga Pech Bak 156 Bo RO Rae RIND EY ac dps Soe Gi ch cP Se seo Se an ee aac ak A ted ls OE ted eS dees 159 Pere SUT COS EING | 5:4 Whe. we: de enw Bava echwty ee A ah ae Ee A ek Wen ah a 162

General Support library man010.02 v

CONTENTS

12.6504: MOD BES.10.. V4.4 oss Boek less ne as Soo we take doe Oa 122% S04. MODABE SAL Wid at torts a! daha hc dee Oe Bae ee ct endo os odes 12.8 SO4.SIN.INT ....... ce A REISS SR yey toys Bek, Seuss An Sue ns PROSTORES ieee Guat etatee enn 4 5 De ti eden ts to EE Caden tan Bele

PAIS AOE Gro, Ree utehe dhe Aeka as Meg Be Hea thee die’ Si UE ak RA Gh eve eRe, ooh

13 X01 Mathematical constants

PIA SOLE E! thes ce hes Mecsas gt geal sce ik Lo wie hace Gols © acre ge gabon bdo hobct le

14 X02 ~— Machine constants

TAL RODEW PSION a 2a cnin § ge erect a4! doe dt oeed Vath bb eee racnce bm a koe 142° X02 MARDBG sp o-So.che oni pA ace hace tS Gow wee Socal ee A SOSA SING oe 1 Ss oss ats oe as ste eds: eee fecal & Econ ot 144 ROR DEANE W2 ren Hides 4 elena tm Baad Meudnhaha a ome ew he 14.5 XO2.MINPW2 ........000. 000000 cece cece eee. 14.6 X0O2.RMAX...................., ene oe ee eee eee HARD RMN Sieh iain Gels, 2. Lom Gg sk Sears deans Geis Bossa dh esc lomdhedita ae VAS XODTOD: chsvotg dy gc ah toed me mooted ove acetone athe Maen dee

15 X05 Other utilities

vi

Toe AU So AMV OGY. ewiie aig & ete Ge gente Dip baled aS dh ho wndiane a Oe 6 ce. 8

EPSON OD SB MAK NG fe cao Bh nalh DR ha eR sD gcd sh heAS S.A he Garten sacbece Goats bast! Poet AUS2 BE MEAX ON «ase eosin oles gh Sy aun, Gogh ig A bee era deeg Poe veg det ud oes EDS KODE S MIN oP Ge 05'S par we Ree Sede Oe a Piel Ad. be ae ecto e eta 15.9 XO5-E_MIN_-PR........ fee Rhee EE Dota ee ew ehh SS Bk

PS LU RO OSES MEIN Vl test bese hed See hee oe aw onal af df hans. < gckee e

man010.02

CONTENTS

187

188

191 192 194 196 198 200 202 204

206

209 211 213 215 217 219 221 223 225 227

229

AMT

CONTENTS CONTENTS

(SPR OSSEEMING V Ric: Osc 4 Uaten ct cn ab ekedee ane wheres 231 1 SMOG ER OH Person ded eis BRA atin OW aoiek kare 4 EG es 233 sie GOT 01 01 eo ke a re ne ee cee ne 236 1S FAKOS TUM PO, outa. cece ewe wee oe ahaa bees eee ener 239 PSS RUS To MAKEPR. 4. cs- ceo eek cy cient aeee eae ye SRO 241 1 PONOE VCs dave gots ok atin Wedd ck eo eh a led exe 243 Te AP KOS TMCV 6, oo a8 40k ohn oe oe hectares +e hee as 245 TSG KOS TO MING RO! 2 go aah oa hick ad ob ee pb a awe 247 PS AOMOG MIN PR no Acuudatanwes pasa Ea eath bene es 249 TBO R05 TS MINGVG io. oc oP Steere dle eae 2 ES wocttal hea ae tice Cita geal 251 PR OEKOS TAMING 40a cd wile eee pe Gedeicltnme CA op hd ee ease eS 253 AG OOK 05 OGD hhc kk Ge oo Gare nORee Lantilh Raci dle ta ob OR 255 1eO8K0Sc LONGAINDEX «.s $.i4 cca ated dawucsien Oe ontelee Nes 258 18.24%08: NORTH -BOUNDARY..6 4.6. .dacdor red obdai ee bueae eee: 260

© | TSG KOS PATRPRN: arf Oo sine d boats eek eels ww uen we ee Be 262 16. 98X05; SCATTERCV. 92° cance San Saw en de bie oid owed 264 ISO TRUSSHLGLEN: & ¢ ou Pecias keratin deh ate ee bod ues Bese 267 PBS ROBSSHU PLOY <5. 05 eo Rigs este hock etd sis care busta een eaten hE Anse 269 {5 99X0S-SHORTAINDEX «4 eee eho eet bd te ee th oak OTL 1b SOK0GSSHRGAIV 2 anctid okies Dea Obie bab eaae e269 Rs 273 IGT RORUSHRELEW 4 Goeth 8 48 Gund om te oo ee Ge eae Son See 275 16 59X08. SOUTH. BOUNDARY 0 :.h.4.¢ ort ooo vcved kh aha bdo 277 {BSSKOS STRETCH <4 ys doe a aed Se nad ee web sabe ves dees 279 1SSERORSTRETOH CS. ooo kane hcln se) Ua eueenede bea Baek 281 1b ASKOSSTRETCH EN GM hho ove be Soy a eee Ch eS a ba ee 283 15:36X08-SUM-LEPTAT ose caa bxw ae ee do a oeuwdoandaeaw nae 285 TS FEROS SUNE RIGHT Ty 24 oceoe up-c a tLe Ape eormewer en, Bhd ARES? 288 {ISRO MINCHINK DES sajna or G hed et be ek hk Oa Ee 291

General Support library man010.02 vil

CONTENTS CONTENTS

15.39X05.WEST. BOUNDARY

vu man0gi10.02 AMT

Chapter 1

Introduction

1.1 Background

The General Support subroutine library was developed at Queen Mary College (QMC) in London and is jointly owned by AMT and QMC. The library is a set of 93 routines which can be called from FORTRAN-PLUS. The contents of the library are based on those of the DAP Fortran library at QMC, which grew in response to user requests for specific routines. The routines were provided © by members of the DAP Support Unit (DAPSU) at QMC, or were written at the suggestion of DAPSU members, or were submitted by users themselves. Many of the algorithms used by these routines have been in regular use on a first generation DAP at QMC since 1980.

1.2 Arrangement of Documentation

The routines described in this manual are classified by chapter, arranged in a NAG-like manner, covering such areas as solution of linear equations, Fourier transforms, and so on. The next chapter in this manual provides a full listing of the contents of the library, chapter by chapter, and gives a brief description of the area covered by each routine.

1.3. Validation

Before being added to the library all routines undergo validation tests, designed and written at DAPSU. These tests have been collected together in a validation suite, which is used to check installation of the library.

General Support library man010.02 1

1.4 FULL-FORM DOCUMENTATION Introduction

1.4 Full-form Documentation

The full description of each routine has eleven sections, covering the following areas:

1 Purpose

Specification Description References Arguments

Error Indicators Auxiliary Routines

Accuracy

oO Oo NN DMD oO BP w pw

Further Comments

me So

Keywords

roy

Example

1.4.1 Purpose

The purpose of the routine is given, and where relevant, details of the area covered by the routine.

1.4.2 Specification

The calling sequence to be used when you invoke the routine. If the routine is written in FORTRAN- PLUS, Specification gives the declaration statements at the head of the routine; if the routine is written in APAL, the equivalent statements are given.

1.4.3 Description

The description of the algorithm used by the routine is given.

1.4.4 References

Any references used in connection with the routine are given.

1.4.5 Arguments

The significance of each argument used by the routine is explained.

2 man010.02 AMT

@- satin

Introduction 1.5 ACCESS TO THE LIBRARY

1.4.6 Error Indicators

' The significance of any error indicators returned by the routine is explained.

1.4.7 Auxiliary routines .

The names of any auxiliary routines used by the routine are given. The auxiliary routines are kept in the same library as the subroutine library routines but are not, in general, available to users.

1.4.8 Accuracy

Some indication is given of the expected accuracy of any result returned by the routine as a result of the method used to calculate it. No information is given about results with respect to the word length used; for such information have a look at the routines in chapter 12 (X02 Machine constants).

1.4.9 Further Comments

Any information which does not fall under any other heading is included here.

1.4.10 Keywords

This section is intended for use with an information retrieval system and gives a list of sub jects to which the operation of the routine may be relevant.

1.4.11 Example

An example program is given (both Host and DAP programs) for each of the routines, showing the use of the routine and any expected results.

WARNING

You should follow closely the specification of the calling sequence given in section 2 of the details of each routine in the following chapters, otherwise you may get unexpected results.

1.5 Access to the Library

The subroutine library is linked in at the consolidation stage of the compiling process. For more details than are included below, see the relevant AMT publication: Program Development Under UNIX (man003), or Program Development Under VAX/VMS (man004).

General Support library man010.02 3

1.6 OTHER AMT SUBROUTINE LIBRARIES Introduction

1.5.1 Using the library under UNIX

The library resides within the UNIX system as: /usr/lib/dap/sulib.dl

and you can use it in a call to dapa or dapf by means of the -1 flag, as in: dapf -o myfile.dd myfile.df -1 sulib

This call will compile the DAP section myfile.df, linking in any routines from the library and produce a DOF file myfile.dd.

1.5.2 Using the library under VAX /VMS

The library resides within the VMS system as: SYS$LIBRARY : GSLIB.DLB

and you can use it in a call to DLINK using the /LIBRARY qualifier, as in: $ DLINK MYFILE,SYS$LIBRARY :GSLIB/LIBRARY

This call links the DAP object code in file MYFILE.DOB with any library routines you might specify in your source code, producing an executable DAP program in file MYFILE.DEX.

Alternatively, you can use the DAP_ LIBRARY logical name, as in: $ DEFINE DAP_LIBRARY SYS$LIBRARY :GSLIB

This call will cause the library to be searched automatically in all subsequent DLINK operations. If you use the library frequently, you may find it convenient to include the above line in your LOGIN.COM file.. If there are several DAP users on your system, your system manager could include the line:

$ DEFINE/SYSTEM DAP_LIBRARY SYS$LIBRARY:GSLIB

in the system startup command file, to give all users automatic access to the library.

1.6 Other AMT subroutine libraries

This General Support subroutine library forms one of a series of libraries available from AMT. Other libraries include:

e Low level graphics library e Signal processing library

e Image Processing library

details of which can be obtained from your local AMT representative.

4 man0g10.02 AMT

Chapter 2

GSLIB quick-reference catalogue

Listed below are the groups of subroutines in release 1 of GSLIB, the General Support subroutine library, and the subroutines in each group; each group is allocated a chapter in this manual. Release 1 of the library is targetted at the DAP 500 series of machines, those with an edge size of 32.

You may find this chapter helpful in the initial selection of suitable routines for the job in hand.

Chapter 3: AO3 Variable precision arithmetic

1 A03_ADD_PLANES_I1 adds bit planes together by performing an addition of n consecutive bits under each processing element. It returns the result of this addition as an INTEGER*1 MATRIX. Any overflow past bit 7 is discarded and the result is given modulo 128.

Chapter 4: C06 Summation of series, including fast Fourier transformations

1 CO6_LFT_LV performs a one dimensional finite Fourier transform of 1024 complex points.

2 CO6_LFT_ESS calculates the two dimensional discrete Fourier transform of 32? com- plex points.

Chapter 5: F01 Matrix operations, including inversion

1 FO1-G_MM performs a general matrix multiply of two matrices A and B where A is a P by Q matrix and B is a Q by R matrix with P, Q and R in the range 1 to 32.

2 FO1_M_INV calculates, in place, the inverse of a given N by N matrix with N in the range 1 to 32.

3 FO1-MM-_STRASSEN uses Strassen’s algorithm to multiply two (partitioned) 64?

matrices.

Chapter 6: F02 Eigenvalues and eigenvectors

General Support library man010.02 5

GSLIB quick-reference catalogue

FO02_ALL_EIG_VALS_TD_LV finds all the eigenvalues of a symmetric tridiagonal

matrix of order up to 1024 using Sturm sequences.

FO2_ALL_EIG_VALS_TD_ES finds all the eigenvalues of a symmetric tridiagonal

matrix of order up to 32 using Sturm sequences.

F0O2_EIG_VALS_TD_LV finds up to 32 selected eigenvalues of a symmetric tridi- agonal matrix of order up to 1024 using Sturm sequences.

F0O2_JACOBI calculates the eigenvalues and eigenvectors of a real symmetric matrix. The method is based on the classical Jacobi algorithm using plane rotations.

Chapter 7: F04 Simultaneous linear equations

1

F04_ BIGSOLVE solves large sets of linear equations. The maximum size of the system depends on the size of the DAP store. The matrix of the coefficients of the equations is of size SIZE by SIZE and the right hand side is assumed to be held in column SIZE+1. The whole matrix is held in the DAP partitioned in DAPSIZE blocks. This routine is not recommended for systems of order 32 or less in this case, you should use the routine F04.GJN_LE_ES.

“F04_GJ_NLE_ES solves for « the system of linear equations Az = b, where A is a

non-sparse matrix of order N (in the range 1 to 32), using the Gauss Jordan method.

F04_QR_GIVENS_SOLVE solves for z the linear system Az = b, where A is an N by N matrix with 2 < N < 33. The routine may be used to solve up to 32 different right hand side vectors 6 simultaneously.

F04.TRIDS_ES returns the solution of a tridiagonal linear system of equations of order up to 32. It finds vector x, where:

Mz=y

and M is a tridiagonal matrix.

F04_TRIDS_ES_SQ returns the solution of a set of up to 32 tridiagonal linear systems of equations each of order up to 32. It solves up to 32 systems of the form:

Mer=y

where M is a tridiagonal matrix.

F04_TRIDS_LV returns the solution of a tridiagonal linear system of equations of order up to 1024. It finds vector z, where:

Me=y

and M is a tridiagonal matrix.

Chapter 8: G05 Random numbers

1

G05_MC_ BEGIN sets the basic generator routine Z-G05. MC-_INT to an initial state.

man0gl10.02 AMT

GSLIB quick-reference catalogue

2 G0O5_MC_I4 returns an INTEGER*4 MATRIX containing 1024 pseudo-random integer numbers taken from a uniform distribution between 0 and 22! 1.

3 G05_MC_I8 returns an INTEGER*8 MATRIX containing 1024 pseudo-random integer numbers taken from a uniform distribution between 1 and 2°9 1.

4 GO5_.MC_NORMAL_R4 returns a REAL*4 MATRIX of 1024 normal pseudo- random variates from the distribution N (0,1).

5 GO5_MC_R4 returns a REAL*4 MATRIX of 1024 pseudo-random real numbers taken from a uniform distribution between 0 and 1.

6 G0O5_MC_R8& returns a REAL*8 MATRIX of 1024 pseudo-random real numbers taken from a uniform distribution between 0 and 1.

7 G05_.MC_REPEAT sets the basic generator routine Z-G05.MC_INT to a repeatable initial state.

Chapter 9: H Operations research, graph structures, networks

1 HO1_L_ASSIGN solves the linear assignment problem with a minimum objective function and a real cost matrix of order N by N, where N <= 32.

Chapter 10: JO6 Plotting

1 JO6_CHAR_CONT returns a character matrix containing a rough contour map of a real matrix. You can control the number of contours and contour levels.

2 JO6_ZEBRA_CHART returns a contour map of a real matrix suitable for output to a printing device. The output is called a ZEBRA chart as it consists of alternating bands of blanks and a given character.

Chapter 11: MO1 Sorting

1 M01_BSORT_LV is based on bitonic sorting. Data is sorted according to a key, or the key alone may be sorted.

2 MO1INV_PERMUTE_COLS permutes the first M columns of a matrix ac- cording to a permutation vector (IV). The routine is equivalent to the FORTRAN-PLUS statements:

DO 10I1=1,M 10 A-PERMUTED(,IV(I) ) = A(,1)

3 M01_INV_PERMUTE_LV_ 32 permutes the values in an INTEGER*4 or REAL*4 matrix using an INTEGER*4 matrix key. The result is written to a new matrix and the orig- inal data is unaffected. The data shuffling implemented is ANSWER (KEY(I)) = START (I), for I = 1, 1024, using long vector indexing. Hence the key matrix must contain values in the range 1 1024, but the values need not be distinct.

General Support library man010.02 7

GSLIB quick-reference catalogue

M01_INV_PERMUTE_ROWS permutes the first M rows of a matrix according to a permutation vector (IV). The routine is equivalent to the FORTRAN-PLUS statements:

DO 101=1,M 10 A.PERMUTED(,IV(I) ) = A(,I)

~M01.PERMUTE_COLS permutes the first M columns of a matrix according to a

permutation vector (IV). The routine is equivalent to the FORTRAN-PLUS statements:

DO 10I1=1,M 10 A.PERMUTED(,I) = A(,IV(I))

M01_PERMUTE_LV_32 permutes the values in an INTEGER*4 or REAL*4 ma- trix using an INTEGER*4 matrix key. The result is written to a new matrix and the original data is unaffected. The data shuffling implemented is ANSWER (I) = START (KEY(D), for I = 1,1024, using long vector indexing. Hence the key matrix must contain values in the range 1 1024, but the values need not be distinct.

M01_PERMUTE_ROWS permutes the first M rows of a matrix according to a permutation vector (IV). The result is equivalent to the FORTRAN-PLUS statements:

DO 101=1,M 10 A.PERMUTED(I,) = A(IV(I),)

M01_SORT_V_14 -sorts the first N elements of an integer vector into ascending or descending order. The permutation required to perform the sort is returned to the calling routine.

M01_SORT_V_R<4 sorts the first N elements of a real vector into ascending or de- scending order. The permutation required to perform the sort is returned to the calling routine.

Chapter 12: S Special functions

1

S04_ARC_COS returns the value of the inverse cosine function arccos (x) for a matrix argument. The result lies in the range (0, 7].

S04. ARC_SIN returns the value of the inverse sine function arcsin (x) for a matrix argument. The result lies in the range [—72/2, 7/2].

S04_ATAN2_M_ is a matrix function similar to the standard FORTRAN ATAN2 function. It calculates arc-tangent(matrix-1/matrix-2), and returns a matrix of values in the range —7 to 7, in the correct quadrant, and with divide-by-zero errors avoided. If a zero divided by zero is attempted then a zero is returned.

$04_ATAN?2-V is a vector function similar to the standard FORTRAN ATAN?2 func- tion. It calculates arc-tangent(vector-1/vector-2), and returns a vector of values in the range —7 to 7, in the correct quadrant, and with divide-by-zero errors avoided. If a zero divided by zero is attempted then a zero is returned.

S04_COS_INT returns the value of the cosine integral C;z for a matrix argument.

man010.02 AMT

GSLIB quick-reference catalogue

9

10

S04_MOD_BES_IO returns the value of the modified Bessel function I0 for a matrix argument.

S04_MOD_BES_I1 returns the value of the modified Bessel function I1 for a matrix argument.

S04_SIN_INT returns the value of the sine integral S;x for a matrix argument. S15_ERF returns the value of the error function.

S15. ERFC returns the value of the complement of the error function.

Chapter 13: X01 Mathematical constants

1

XO1_PI determines the value of x for any of the real precision lengths available on the DAP.

Chapter 14: X02 Machine constants

1

X02_EPSILON determines the smallest positive real (EPS) such that 1.0+EPS differs from 1.0, for any of the real precision lengths available on the DAP.

X02_MAXDEC determines the value of MAXDEC for the different precision lengths available on the DAP. MAXDEC is the maximum number of decimal digits which can be represented accurately over the whole range of floating point numbers.

X0O2_MAXINT determines the value of MAXINT for the different precision lengths available on the DAP. MAXINT is the largest integer such that MAXINT and -MAXINT can both be represented accuratetly.

X02_MAXPW2 determines the value of MAXPW2 for the different precision lengths available on the DAP. MAXPW2 is the largest integer power to which 2.0 may be raised without overflow.

X02_MINPW2 determines the value of MINPW2 for the different precision lengths available on the DAP. MINPW2 is the largest negative integer power to which 2.0 may be raised without underflow.

X02_RMAX determines the largest real (RMAX) such that RMAX and -RMAX can both be represented exactly, for any of the real precision lengths available on the DAP.

X0O2_RMIN determines the smallest real (RMIN) such that RMIN and -RMIN can both be represented exactly, for any of the real precision lengths available on the DAP.

X02_TOL determines the value of TOL (= RMIN/EPSILON) for any of the precision lengths available on the DAP.

General Support library man010.02 9

GSLIB quick-reference catalogue

Chapter 15: X05 Other utilities

1

10

11

12

10

X05_ALT_LV produces a long vector of alternating groups of N false values followed by N true values and so on, until all components of the vector have a value. If the value of N lies outside the range 1 to 1024 all components will have the value false.

X05_CRINKLE effects a transformation in data storage format for vertical mode data occupying an array of matrices from ‘sliced’ to ‘crinkled’ storage.

X05_EAST_BOUNDARY returns a logical matrix containing at most one .TRUE.

in each row corresponding to the last .TRUE. (if any) in each row of the logical matrix parameter. The routine is equivalent to the FORTRAN-PLUS code:

DO 101 = 1, 32

IF (NOT. ANY (LM(I,))) GOTO 10

KM (I,) = REV(FRST (REV (LM (1, )))) 10 CONTINUE

X05_E_MAX_PC returns a logical matrix whose it* row has the value .TRUE. in the position(s) corresponding to the position(s) in the i** row of the real matrix argument holding the maximum value in that row, and .FALSE. elsewhere.

X05_E.MAX_PR returns a logical matrix whose i** column has the value TRUE. in the position(s) corresponding to the position(s) in the i** column of the real matrix argument holding the maximum value in that column, and .FALSE. elsewhere.

X05_E_MAX_VC returns a real vector whose i” component is the maximum value in the i** row of the real matrix argument.

X05_E_MAX_VR returns a real vector whose i** component is the maximum value in the i** column of the real matrix argument.

X05_E_MIN_PC returns a logical matrix whose i** row has the value .TRUE. in the position(s) corresponding to the position(s) in the it* row of the real matrix argument holding the minimum value in that row, and .FALSE. elsewhere.

X05. E_MIN_PR returns a logical matrix whose i* column has the value TRUE. in the position(s) corresponding to the position(s) in the i** column of the real matrix argument holding the minimum value in that column, and .FALSE. elsewhere.

X05. E.MIN_VC returns a real vector whose it” component is the minimum value in the z** row of the real matrix argument.

X05_E_MIN_VR returns a real vector whose it* component is the minimum value in the i** column of the real matrix argument.

X05. EXCH_P exchanges L planes starting at X with L planes starting at Y under

activity control indicated by M. The planes are exchanged in increasing order; you are cautioned about the strange effects which will occur if the two sets of planes overlap.

man010,02 AMT

GSLIB quick-reference catalogue

13

14

15

16

17

18

19

20

21

22

23

24

X05_GATHER_V_ 32 assigns to the components of a vector the values of those components of a vector array designated by corresponding components of an indexing vector. The index values are interpreted as reduced rank indices to the vector array.

X05_I_-MAX_PC returns a logical matrix whose i‘* row has the value .TRUE. in the position(s) corresponding to the position(s) in the i‘* row of the integer-matrix argument holding the maximum value in that row, and .FALSE. elsewhere.

X05_I.MAX_PR returns a logical matrix whose i** column has the value .TRUE. in the position(s) corresponding to the position(s) in the 7** column of the integer matrix

argument holding the maximum value in that column, and .FALSE. elsewhere.

X05_I.MAX_VC returns an integer vector whose i** component is the maximum value in the i*" row of the integer matrix argument.

X05_I.MAX_VR_ returns an integer vector whose i#* component is the maximum

- value in the i** column of the integer matrix argument.

X05_I.MIN_PC returns a logical matrix whose i** row has the value .TRUE. in the position(s) corresponding to the position(s) in the i** row of the integer matrix argument holding the minimum value in that row, and .FALSE. elsewhere.

X05_I_MIN_PR _ returns a logical matrix whose i** column has the value . TRUE. in the position(s) corresponding to the position(s) in the i** column of the integer matrix argument holding the minimum value in that column, and .FALSE. elsewhere.

X05_I_ MIN-_VC returns an integer vector whose i** component is the minimum value in the i" row of the integer matrix argument.

X05_I_MIN_VR returns an integer vector whose i** component is the minimum value in the 7** column of the integer matrix argument.

X05_LOG2 returns the value: [log(N—1)]+1

where square brackets indicate ‘integer part of’, and N is the input argument. The routine returns the number of steps required in a logo, recursive doubling, algorithm.

X05. LONG_INDEX generates an integer matrix whose i‘ element in long vector order is ( + N 1), where N is a parameter to the routine.

X05_NORTH.-BOUNDARY returns a logical matrix containing at most one

-TRUE. in each column corresponding to the first .TRUE. (if any) in each column of the logical matrix parameter. The routine is equivalent to the FORTRAN-PLUS code:

DO 101 = 1, 32 IF (NOT. ANY (LM(,I))) GOTO 10 KM (,I) = FRST (LM (,1))

10 CONTINUE

General Support library man010.02 11

25

26

27

28

29

30

31

32

33

34

35

36

12

GSLIB quick-reference catalogue

X05. PATTERN produces four user-selectable patterns, each of which is returned as a logical matrix. The four patterns available are:

0 ~ The main diagonal 1 - The minor diagonal 2 —- A matrix, the rows of which correspond to the rows generated by ALTC

3 ~ The unit lower triangular matrix

X05_SCATTER_V_ 32 takes components of a vector and assigns the values to com- ponents of a vector array designated by corresponding components of an indexing vector. The index values are interpreted as reduced rank indices to the vector array.

X05_SHLC_LV performs a cyclic long vector shift to the left on up to 128 bit planes. X05.SHLP-_LV performs a planar long vector shift to the left on up to 128 bit planes.

X05.SHORT_INDEX generates an integer vector whose i** element is (i + N - 1),

where N is a parameter to the routine. X05_SHRC_LV performs a cyclic long vector shift to the right on up to 128 bit planes.

X05_.SHRP_LV performs a planar long vector shift to the right on up to 128 bit planes.

X05_.SOUTH_. BOUNDARY returns a logical matrix containing at most one

-TRUE. in each column corresponding to the last .TRUE. (if any) in each column of the logical matrix parameter. The routine is equivalent to the FORTRAN-PLUS code:

DO 101 =1, 32

IF (.NOT. ANY (LM (,I))) GOTO 10

KM (,1) = REV(FRST (REV (LM (,1)))) 10 CONTINUE

X05_STRETCH_4 stretches the first quarter of a real matrix A (considered as a long vector), such that each element is repeated four times consecutively.

X05_STRETCHL8 stretches the first eighth of a real matrix A (considered as a long

vector), such that each element is repeated eight times consecutively.

X05.STRETCHL_N stretches the first NtP of a real matrix A (considered as a long vector), such that each element is repeated N times consecutively, N being 2 raised to a positive integer power.

X05_-SUM.LEFT_1I2 takes as input the long vector A (an INTEGER*2 vector) and

returns an INTEGER*2 long vector each of whose elements is the sum of all the elements on the left of, but not including, the corresponding element of A. #

man010.02 AMT

GSLIB quick-reference catalogue

37 X05_SUM_RIGHT_1I2 takes as input the long vector A (an INTEGER*2 vector) and returns an INTEGER*2 long vector each of whose elements is the sum of all the elements on the right of , but not including, the corresponding element of A.

38 XO5_UNCRINKLE effects a transformation in data storage format for vertical mode data occupying an array of matrices from ‘crinkled’ to ‘sliced’ storage.

39 X05_WEST_BOUNDARY returns a logical matrix containing at most one .TRUE. in each row corresponding to the first .TRUE. (if any) in each row of the logical matrix parameter. The routine is equivalent to the FORTRAN-PLUS code:

DO 101=1, 32 IF (.NOT. ANY (LM, (I,))) GOTO 10 KM (I,) = FRST(LM(I,))

10 CONTINUE

General Support library man010.02 13

14

man010.02

GSLIB quick-reference catalogue

AMT

Chapter 3

A03 Variable precision

arithmetic Contents: Subroutine Page

A03_ADD. PLANES_I1 16

General Support library man010.02 15

3.1 A03_ADD.PLANES_TIi A03 Variable precision arithmetic

sve I A03_ADD_PLANES_I1 . release 1

16

Purpose

A03_ADD_PLANES_Ii adds bit planes together, that is, it performs an addition of n con- secutive bits of each PE.

A03_ADD_PLANES_I1 returns the result of this addition so that the corresponding element of the result is the sum of the n consecutive bits of the corresponding PE.

The result is calculated to an accuracy of integer*1, therefore any overflow past bit 7 is thrown away and the result is modulo 128.

Specification

INTEGER*1 MATRIX FUNCTION A03_ADD_PLANES_I1 (STARTPLANE , + NRPLANES)

INTEGER NRPLANES

<any type> STARTPLANKE(,)

Description

The DAP can add the contents of a store plane and the Q and C planes simultaneously ; this routine uses that ability to add pairs of planes. The resulting carry is then rippled up the answer.

References

None

Arguments STARTPLANE - <any type> MATRIX

On entry STARTPLANE contains the address of the first plane to be added. The function adds NRPLANES consecutive planes starting at STARTPLANE.-START- PLANE may, in FORTRAN-PLUS, be any variable represented by a plane address. None of the planes added are changed by the function, but you are warned against allowing the destination of the result to overlap the planes to be added. If you do try overlapping the planes, the program will still work, but you will have overwritten your arguments before you accessed them!

NRPLANES - INTEGER On entry NRPLANES specifies the number of planes to be added. Unchanged on exit.

Error Indicators

None

Auxiliary Routines

None

Accuracy

The results are calculated mod 128 - overflow is not detected.

man010.02 AMT

A03 Variable precision arithmetic 3.1 AO3_ADD.PLANES_II

9 Further Comments

None

10 Keywords

Bit summation, integer addition.

11 Example

The example adds the bit planes which define a long index vector, thus counting the number of bits set .TRUE. in the binary representation of the integers 0 to 1023.

Host program

PROGRAM MAIN

INTEGER IM(1024) COMMON /IM/IM

CALL DAPCON(?’ ent.dd?’) CALL DAPENT(? ENT?) CALL DAPREC(?IM? ,IM, 1024)

WRITE(6, 1000) 1000 “FORMAT(6X,’I’,3X,’No. of bits set’//) DO 10 II=1,1024

© ; I=II-1 ' 40» WRITE(6,2000) I,IM(IZ) 2000 FORMAT(I7,10X,12)

CALL DAPREL STOP END

DAP program

ENTRY SUBROUTINE ENT INTEGER*1 IM1(,) INTEGER IM(,) LOGICAL LM(, ,32) COMMON /IM/IM EQUIVALENCE (IM,LM)

EXTERNAL INTEGER*1 MATRIX FUNCTION AO3_ADD_PLANES I1

General Support library man0Q10.02 17

3.1 A03_ADD_PLANES_Ii A03 ~ Variable precision arithmetic

CALL XOSLONGINDEX(IM,0) IM1=A03_ADD_PLANES_Ii(LM(, ,21),10) IM=IM1

CALL CONVMFI(IM)

RETURN END

Results ~

I No. of bits set

0 0 1 1 2 1 3 2 1020 8 1021 9 1022 9 1023 10

18 man010.02 AMT

Chapter 4

C06 _ Summation of