From: LAMSON SCOTT H               <LAMSON@ge-crd.arpa>
Date:  4 Jun 87 20:42 EST


Date:  3-JUN-1987 13:29
From: S.H. Lamson
Sender: LAMSON
Subject: text of sciport report
To: dongarra@anl-mcs.ARPA@smtp@tcpgateway
--------
.PH ""
.po 1i
.SA 1
.nr Cl 3
.tr  
.br
.rs
.sp 12
.ce 2
.ul 2
A Reference Manual for SCIPORT,
A Portable Implementation of CRAY SCILIB Mathematical Library
.sp 2
.ce 2
by
M.J. McBride and S.H. Lamson
.sp 1
.ce 4
Information System Operation
General Electric Corporate Research and Development
Schenectady, New York 12301
Copyright, General Electric Co, 1986
.fi
.bp
.ce 1
.ul 1
Abstract
.sp2
     SCIPORT is a portable FORTRAN emulation of CRAY SCILIB, a
library of scientific applications subprograms developed by Cray
Research, Inc. for use with its CRAY supercomputers.  SCIPORT was
developed by the Information System Operation of Corporate Research
and Development to enhance convertibility between local computers
and CRAY supercomputers.  Due to its portability, SCIPORT allows
development of applications software on almost any computer with
desirable software development tools (e.g. IBM, VAX, SUN workstations).
The SCILIB-type calls of SCIPORT then allow the use of the CRAY
supercomputer for production runs with no required changes in the
applications software.  SCIPORT also provides a useful library of
mathematical utilities for applications which do not require
the use of a CRAY supercomputer.
.bp
.ce 1
.ul 1
Acknowledgments
.sp2
     The authors wish to acknowledge the assistance of J. Conklin and
J. Kane in setting up and describing the installation procedures for
the VAX/VMS and UNIX environments, respectively.  In addition, we would like
to express our appreciation to ISO management, C. Forth in particular,
for organizing the GE-Siena Internship Program which supported M. McBride
and for selecting this project for funding under the program's second year.
.sp
.in 10
.ds HF 2 2 1
.nr Ej 1
.nr Hc 1
.nr Hi 2
.nr Hs 2
.nr Hb 4
.nr Pt 1
.nr O 1i
.pn 1
.bp
.PF "''- % -''"
.sp1
.H 1 "Overview"
.sp1
.H 2 "Introduction"
.sp1
Requirements for large-scale computational resources have led
General Electric Corporate Research and Development to obtain access to a
CRAY supercomputer under an arrangement with Research Equipment Inc., a
wholly owned subsidiary of the University of Minnesota.  Research staff
in engineering and science at CRD have found many diverse applications for the
computing power offered by CRAY architecture.  At the same time, most users
have found the maintenance of applications codes on multiple
computer systems a burdensome task.
The effort required is exacerbated in a research and development environment
by the ongoing evolution of applications codes
to handle more general and more complex requirements.
In addition, the support environment
for applications development on number-crunching supercomputers is very
poor compared with local systems like workstations and VAX
super-minicomputers.  Therefore, it is desirable to develop and debug
applications software in the local environment which supports better
software tools and interactive access.  More efficient use of the CRAY
is realized when its CPU is available for production runs and algorithm
testing, situations in which the computational requirements are too large
for local facilities.  However, in order to optimize performance of codes
targeted for supercomputers, the emulation of some CRAY-specific utilities
on the local machines is essential.  One such effective utility is the
CRAY SCILIB library of mathematical routines which perform general-purpose
functions like vector dot products, matrix multiplications, recurrence
relations, and sparse matrix primitives.  The use of these utilities
has the advantage both of compressing repetitive sequences of FORTRAN
statements into single function or subroutine calls and of gaining high
efficiency by using assembly language coded functions.
     The goal of the SCIPORT project is to enhance convertibility
between local computer systems, where applications are developed, and the
CRAY environment, which is optimally suited to production use.  SCIPORT
provides a portable FORTRAN library of mathematical routines on local 
computer systems which reproduce the functions provided by Cray Research
in SCILIB.  Thus, the user developing applications locally uses
SCILIB-type calls during program development and is assured that the
results will be consistent (within floating point precision) between
the local computer and the CRAY.
.sp1
     In addition to the benefits outlined above, SCIPORT also provides a
resource of generic, compact, and efficient mathematical utilities to
local computer users, decoupled from the supercomputer development activity.
The utilities, such as the BLAS (Basic Linear Algebra Subroutines),
which are included in SCIPORT, are commonly used standards in mathematical
software and occur frequently in higher-level libraries like LINPACK,
EISPACK, and others.
.sp1
.H 2 "SCIPORT Libraries"
.sp1
SCIPORT consists of three libraries:  two object libraries
and a help library.  The object libraries are SCIPORTS, which provides
single precision (32-bit on VAX) floating point representation, and SCIPORTD,
which provides double precision (64-bit on VAX) floating point representation.
Examples of the use of each object library in a VAX/VMS environment follow:
.sp2
.nf
     single precision
        $ LINK file1,file2,...,fileN,USR$LIBRARY:SCIPORTS/LIB
.sp1
     double precision
        $ LINK file1,file2,...,fileN,USR$LIBRARY:SCIPORTD/LIB
.sp2
.fi
For the VAX/VMS system, an on-line help facility has been implemented to
provide assistance to users of SCIPORT.  Information
is available for each routine including the purpose of the routine, the
required FORTRAN call statement, and a description of each parameter in the
parameter list.  This facility will also be of help to users of CRAY SCILIB
since the use of the two libraries is so similar.
.sp1
.H 2 "Test Procedures"
.sp1
Extensive test procedures are available for SCIPORT.  These procedures 
validate the requirement that SCIPORT routines reproduce, within numerical
accuracy, the results of CRAY SCILIB routines.  Each group of routines
(e.g. BLAS, SEARCH) has its own set of test drivers and test case database.
Further information is available in the appendices; Appendix A for
instructions for the installation and testing of SCIPORT in a VAX/VMS
environment; Appendix B for instructions on the installation and testing
of SCIPORT in a UNIX environment; and Appendix C for instructions on
adding additional test case data.
.sp1
.H 1 "Detailed Description of SCIPORT"
.sp1
.H 2 "SCIPORT Help Documentation"
.sp1
SCIPORT is divided into seven groups according to the divisions used for
SCILIB in the CRAY Library Reference Manual, Chapter four [1].  Sections
2.1.1 to 2.1.7 contain general descriptions of the groups as well as
detailed descriptions of each subprogram.  This material is also available
as on-line help in the VAX/VMS environment.  It essentially reproduces the
documentation provided by Cray Research, Inc. in the library reference
manual, and is reproduced here with their consent [5].
.sp2
.H 3 "Basic Linear Algebra Subprograms (BLAS)"
.sp1
A group of thirty-three subprograms that perform operations using
absolute values, vector arithmetic, array copying and swapping, Givens
plane rotation, Euclidean norms, indices of minimum and maximum values,
vector summing, etc.  Routines include:
.nf
.sp1
    ISAMAX     ICAMAX     SASUM      SCASUM     SAXPY      CAXPY
    SCOPY      CCOPY      SDOT       CDOTC      CDOTU      SNRM2
    SCNRM2     SROTG      SROT       SROTMG     SROTM      SSCAL
    CSSCAL     CSCAL      SSWAP      CSWAP      SPAXPY     SPDOT
    ISMAX      ISMIN      ISAMIN     SSUM       CSUM       CROTG
    CROT       SMACH      CMACH
.sp2
**** CRI copyrighted documentation deleted ***
.bp
.H 3 "SEARCH/WHEN/ordered search"
.fi
.sp1
A group of thirty-four subroutines that perform searches for locating the
number or positions of true occurences within a vector, for finding the
first occurence of a target object within a vector, for finding the indices
of all positions of an object within a vector, and for finding targets within
ordered arrays.  Routines include:
.nf
.sp1
  IILZ       IFLZ       ILLZ       ILIZ       ILFZ       ILSUM
  IISUM      IFSUM      ISRCHFEQ   ISRCHFNE   ISRCHFLT   ISRCHFLE
  ISRCHFGT   ISRCHFGE   ISRCHIEQ   ISRCHINE   ISRCHILT   ISRCHILE
  ISRCHIGT   ISRCHIGE   WHENFEQ    WHENFNE    WHENFLT    WHENFLE
  WHENFGT    WHENFGE    WHENIEQ    WHENINE    WHENILT    WHENILE
  WHENIGT    WHENIGE    OSRCHI     OSRCHF
.sp2
**** CRI copyrighted documentation deleted ***
.bp
.H 3 "Linear Recurrence"
.fi
.sp1
A group of eight subprograms that solve first-order and some second-order
linear recurrences.  A linear recurrence is an evaluation of a quantity,
term by term, from given initial values and from previously computed values.
Routines include:
.nf
.sp1
  FOLR       FOLRP      FOLR2      FOLR2P     FOLRN      SOLR
  SOLRN      SOLR3
.sp2
**** CRI copyrighted documentation deleted ***
.bp
.H 3 "Matrix Utilities"
.fi
.sp1
A group of five subroutines that compute a matrix inverse, solve systems of
linear equations using Gauss-Jordan elimination, and provide for optimal
matrix multiplication for different categories of matrices.  Routines include:
.nf
.sp1
  MINV       MXM        MXV        MXMA       MXVA
.sp2
**** CRI copyrighted documentation deleted ***
.bp
.H 3 "Fast Fourier Transforms (FFT)"
.fi
.sp1
A group of three subprograms that apply a fast Fourier transform and compute
either a Fourier analysis or a Fourier synthesis.  Routines include:
.nf
.sp1
  CFFT2      RCFFT2     CRFFT2
.sp2
**** CRI copyrighted documentation deleted ***
.bp
.H 3 "Filters"
.fi
.sp1
A group of three subprograms used for filter analysis and design.  They can
also be used to solve more general problems.  Routines include:
.nf
.sp1
  FILTERG    FILTERS    OPFILT
.sp2
**** CRI copyrighted documentation deleted ***
.bp
.H 3 "Gather/Scatter"
.fi
.sp1
A pair of subroutines that allow the user to gather a vector from a source
vector or to scatter a vector into another vector.  A third vector of indices
determines which elements are accessed or changed.  Routines include:
.nf
.sp1
  GATHER     SCATTER
.sp2
**** CRI copyrighted documentation deleted ***
.bp
.fi
.H 3 "LINPACK"
.sp1
LINPACK is a package of FORTRAN routines that solve systems of linear
equations and compute the QR, Cholesky, and singular value decompositions.
The original FORTRAN programs are documented in the LINPACK User's Guide [2].
.sp3
.H 3 "EISPACK"
.sp1
EISPACK is a package of FORTRAN routines for solving the eigenvalue problem,
computing and using the singular value decomposition, and solving banded
symmetric systems of linear equations.  The original FORTRAN versions are
documented in the Matrix Eigensystem Routines - EISPACK Guide [3]
.bp
.H 2 "Differences between SCIPORT and SCILIB"
.fi
.sp1
In setting up the utilities to be included in SCILIB, Cray Research
made an assumption that is valid for the present CRAY architecture.
Namely, several SCILIB routines assume that both floating point and integer
variables are stored in words of equal length.  CRAY words are all 64-bit,
and both integer and single precision FORTRAN variables (the normal floating
point type used in our experience) are maintained in a single word.  Similar
large-scale computing, when done on a VAX or other 32-bit system, often still
requires 64-bit floating point precision, whereas integers are kept in single
32-bit words.  In a general computer system, then, the assumption that
integers and floating point data are in equal-length storage is not valid.
Therefore, routines in SCILIB that are based on this assumption cannot be
implemented with identical syntax in SCIPORT.
     In most SCILIB routines, integer and floating point versions are
distinguished by an 'I' or 'F' in the name.  Where integer and floating point
versions are the same internally, no distinction is made in the name.  In
SCIPORT, however, there is always the need to make the distinction, so both
integer and floating point versions have been created for all routines.
The routines in which these differences occur are found in the
SEARCH/WHEN/ordered search group.  They include ISRCHIEQ and ISRCHFEQ for
SCILIB's ISRCHEQ, ISRCHINE and ISRCHFNE for SCILIB's ISRCHNE, WHENIEQ and
WHENFEQ for SCILIB's WHENEQ, WHENINE and WHENFNE for SCILIB's WHENNE, IILZ
and IFLZ for SCILIB's IILZ, ILIZ and ILFZ and ILLZ for SCILIB's ILLZ, and
IISUM and IFSUM and ILSUM for SCILIB's ILSUM.  The latter two also include
logical versions, using 'L' to indicate logical.  Note that utilities in
SCILIB which test for "greater than" or "less than" do distinguish floating
point versions from integer versions, whereas utilities which test for
"equal" or "not equal" do not make the distinction.  SCIPORT extends the
SCILIB naming convention to the latter utilities because of the potential
differences in word length.
     In order to expedite the use of the SCIPORT calls which are not part of
the SCILIB defined calls on the CRAY (e.g. ISRCHIEQ, ISRCHFEQ), CRAY sites
may add entry points to their SCILIB assembly language modules to allow
SCILIB routines such as ISRCHEQ to be called with SCIPORT names such as
ISRCHIEQ and ISRCHFEQ.  Future releases of SCILIB may include these additional
entry points for the search routines.
     Table 2-1 is a listing of the previously mentioned SCILIB modules and
the SCIPORT-compatible entry points that have been added to the SCILIB
library at the University of Minnesota, and would need to be added to any
CRAY supercomputer site desiring full compatibility with SCIPORT.
.sp2
.DS
.ce2
Table 2-1
.sp1
SCILIB modules and SCIPORT-compatible entry points
.TS
center,box,tab(:);
c c c c
c c c c
c c c c
c s s s
l l l l.
:floating::
SCILIB:point:integer:logical
module:entry:entry:entry
---------------------------------------
:::
ISRCHEQ:ISRCHFEQ:ISRCHIEQ:
ISRCHNE:ISRCHFNE:ISRCHINE:
WHENEQ:WHENFEQ:WHENIEQ:
WHENNE:WHENFNE:WHENINE:
IILZ:IFLZ:IILZ:
ILLZ:ILFZ:ILIZ:ILLZ
ILSUM:IFSUM:IISUM:ILSUM
.TE
.DE
.sp2
.H 2 "Options for More Efficient Code"
.sp1
As the generic modules provided in SCIPORT are so wide-spread in
computationally intensive CAE and scientific applications, efficiency of
execution is a vital issue.  The portable FORTRAN implementation provides
portability, but its efficiency is dependent on the quality of the code
generated by the available FORTRAN compiler.  More efficient code may be
produced by C language implementations which retain the advantages of
portability.
Further efficiency gains may be achieved by machine-specific assembly
language implementations of key modules.  Initial tests indicate this route
offers efficiency improvements of 10% on a VAX/VMS system, whose FORTRAN
compiler is quite well developed.  About six routines (in both precisions)
will be written
in C and/or VAX assembly language for these reasons.  Where the C versions
are more efficient and/or assembly language coding can be justified, the
FORTRAN implementations will be superseded by a more efficient implementation.
The test case database may then be applied to check the updated library for
correct results automatically.
.sp1
.H 2 "Conclusion"
.sp1
SCIPORT is a well-documented, easy-to-use library that optimizes use of
the CRAY service by utilizing the best features of a local minicomputer or
workstation in
conjunction with the best features of a CRAY supercomputer.  
The on-line help feature that is available with SCIPORT
under VAX/VMS will make it much
easier to use both SCIPORT and CRAY SCILIB because of the similarities between
the two libraries.
.sp1
.bp
.HU "APPENDIX A:  SCIPORT Installation in a VAX/VMS environment"
.sp1
     The SCIPORT tape (available from S. Lamson, Dialcomm 8*833-5795)
contains single and double precision FORTRAN files, data files for testing,
and a help file.  The FORTRAN files are used to create two object libraries,
SCIPORTS for single precision and SCIPORTD for double precision, and
executable images for the testing procedures.  The data files contain test
data with SCILIB results to be compared with the SCIPORT results obtained
during the execution of the testing procedures.  The help file is
used to create the on-line help library to be used in conjunction with
SCIPORT.  Tables A-1 to A-3 give all of the files that are necessary to
create and test the object libraries as well as the file needed to create
the help library.
.sp2
.DS
.ce2
Table A-1
.sp1
Source files for SCIPORT
.TS
center,box,tab(:);
c c c
c c c
c s s
l l l.
File::
name:Precision:Description
-----------------------------------------------------------------
::
BLASS.FOR:Single:Basic Linear Algebra Subprograms
SEARCHS.FOR:Single:Search/When/Ordered Search subprograms
LINRECS.FOR:Single:Linear Recurrence subprograms
MATRIXS.FOR:Single:Matrix Utilities subprograms
FFTS.FOR:Single:Fast Fourier Transform subprograms
FILTERS.FOR:Single:Filter subprograms
GATSCATS.FOR:Single:Gather/Scatter subprograms
LINPACKS.FOR:Single:LINPACK
EISPACKS.FOR:Single:EISPACK
::
BLASD.FOR:Double:Basic Linear Algebra Subprograms
SEARCHD.FOR:Double:Search/When/Ordered Search subprograms
LINRECD.FOR:Double:Linear Recurrence subprograms
MATRIXD.FOR:Double:Matrix Utilities subprograms
FFTD.FOR:Double:Fast Fourier Transform subprograms
FILTERD.FOR:Double:Filter subprograms
GATSCATD.FOR:Double:Gather/Scatter subprograms
LINPACKD.FOR:Double:LINPACK
EISPACKD.FOR:Double:EISPACK
.TE
.DE
.sp2
.DS
.ce2
Table A-2
.sp1
Test driver files for testing SCIPORT
.TS
center,box,tab(:);
c c c
c c c
c s s
l l l.
File::
name:Precision:Description
--------------------------------------------------------------------
::
DRBLASS.FOR:Single:Test driver for BLAS
DRSRCHS.FOR:Single:Test driver for SEARCH/WHEN/Ordered Search
DRLINRS.FOR:Single:Test driver for Linear Recurrence
DRMATS.FOR:Single:Test driver for Matrix Utilities
DRFFTS.FOR:Single:Test driver for FFT
DRFILTS.FOR:Single:Test driver for filters
DRGATS.FOR:Single:Test driver for Gather/Scatter
::
DRBLASD.FOR:Double:Test driver for BLAS
DRSRCHD.FOR:Double:Test driver for SEARCH/WHEN/Ordered Search
DRLINRD.FOR:Double:Test driver for Linear Recurrence
DRMATD.FOR:Double:Test driver for Matrix Utilities
DRFFTD.FOR:Double:Test driver for FFT
DRFILTD.FOR:Double:Test driver for filters
DRGATD.FOR:Double:Test driver for Gather/Scatter
.TE
.DE
.sp2
.DS
.ce2
Table A-3
.sp1
Data files for testing SCIPORT
.TS
center,box,tab(:);
c c
c c
c s
l l.
File:
name:Description
---------------------------------------------------------------
:
BLAS.DAT:Test database for BLAS
SEARCH.DAT:Test database for SEARCH/WHEN/Ordered Search
LINREC.DAT:Test database for Linear Recurrence
MATRIX.DAT:Test database for Matrix Utilities
FFT.DAT:Test database for FFT
FILTER.DAT:Test database for filters
GATSCAT.DAT:Test database for Gather/Scatter
:       ------
SCIPORT.HLP:Help file for creating help library
.TE
.DE
.sp1
     The SCIPORT tape is read using the VMS BACKUP command.  The tape consists
of two savesets.  The first saveset contains only the SCIPORT installation
procedure.  The second saveset contains the SCIPORT FORTRAN source files, data
files, maintenance procedures, and a HELP file.  Use the following steps to
install SCIPORT on your system:
.nf
.sp1
.DS
(1) Create a directory for the SCIPORT software and SET DEFAULT
    there.
.sp1
        $ CREATE/DIRECTORY disk_name:[directory_name]
        $ SET DEFAULT disk_name:[directory_name]
.DE
.sp1
.DS
(2) The SCIPORT tape must be mounted on the physical device
    whose logical name is SYS$TAPE, since the installation
    procedure assumes this.  You need to ASSIGN this logical
    to the tape drive you're using before doing the MOUNT
    command.  The device name is probably something like MFA0,
    MSA0, etc.
.sp1
        $ ASSIGN device_name SYS$TAPE:
        $ MOUNT/FOREIGN SYS$TAPE:
.DE
.sp1
.DS
(3) Copy the first saveset from the tape.
.sp1
        $ BACKUP/REWIND SYS$TAPE:SCIPORT1.SAV */OWNER=PARENT
.DE
.sp1
.DS
(4) Now, simply run the SCIPORT installation procedure.  This
    will load the source files, do the necessary compilations
    and links, and run the test drivers.  This procedure takes
    approximately 15 minutes, depending on the load of your
    system.
.sp1
        $ @SCIINSTAL
.DE
.sp1
.DS
(5) If the installation was successful, the SCIPORTS.OLB and
    SCIPORTD.OLB object libraries just created should be moved
    to a directory where they will be accessible to users.
    Alternatively, you can create a logical pointing to the
    SCIPORT directory you created at the beginning of the
    installation by using the following command.
.sp1
       $ ASSIGN/SYSTEM disk_name:[directory_name] SCIPORT$DIRECTORY:
.DE
.sp1
.DS
(6) The SCIINSTAL procedure also created a SCIPORT.HLB help
    library from the SCIPORT.HLP file included on the tape.
    You may wish to execute the following command to make the
    help library accessible to users via the VMS HELP command.
    Make sure HLP$LIBRARY_1 is not already assigned to a
    previously created help library on your system.  If it is,
    simply use HLP$LIBRARY_2, HLP$LIBRARY_3, etc.
.sp1
        $ ASSIGN/SYSTEM disk_name:[directory_name]SCIPORT.HLB
          HLP$LIBRARY_1:
.sp1
    Alternatively, you can insert the SCIPORT.HLP file into
    an already existing help library somewhere on your system.  
.DE
.bp
.HU "APPENDIX B:  SCIPORT Installation in a UNIX Environment"
.fi
.sp1
     Installation of SCIPORT software will require 12,000
kilobytes of disk storage.
.nf
.sp1
(1) Log in as a non-privileged user.
.sp1
.DS
(2) Change your directory to an empty directory in which you
    wish to load the SCIPORT software (e.g. /usr/sciport).
.DE
.sp1
.DS
(3) Mount the tape on a tape drive and type the following:
.sp1
        tar xv ./sciinstal
.DE
.sp1
.DS
(4) After the file sciinstal has been loaded from tape, type
    the following:
.sp1
        sciinstal
.sp1
    NOTE: At this time, several messages will appear on the
          terminal as the software is compiled and linked and
          the installation verified.  There should be no error
          messages.
.DE
.sp1
.DS
(5) When the installation is complete, log in as root and copy
    sciport.1 to /usr/man/man1.  The SCIPORT manual information
    can now be obtained by typing:
.sp1
        man sciport
.DE
.bp
.fi
.HU "APPENDIX C:  Adding Tests to Data Files"
.sp1
     Each group of subprograms that is described in section 2.1 has a test data
file to test each of its subprograms.  The format of these files is designed
to be self-explanatory.  One file contains many test cases separated by one
or more blank lines.  The last case in each file is followed by XXX, which
terminates execution.  The following example should help to make adding
test cases a simpler task:
.nf
.sp1
     Example of Test Cases in Data Files:
.sp1
.DS
  SASUM                          B005 07/15/85 MJM 08/07/85 Inc>1.
  CRAY-1/S COS 1.12 CFT 1.11
  'NUMBER'     5
  'INCX'       2
  'VECTOR X'   1.0  2.0  -3.0  4.0  -5.0
  'SUM'        9.0
.DE
.sp2
.DS
  SDOT                           B018 07/23/85 MJM 08/07/85 Product=0.
  CRAY-1/S COS 1.12 CFT 1.11
  'NUMBER'     5
  'INCX,INCY'  1  1
  'VECTOR X'   1.0  2.0  3.0  4.0  5.0
  'VECTOR Y'   -5.0  -4.0  0.0  2.0  1.0
  'RESULT'     0.0
.DE
.sp2
.DS
  SAXPY                          B045 07/25/85 SHL 08/07/85 Inc=1.
  CRAY-1/S COS 1.12 CFT 1.11
  'NUMBER'     4
  'INCX,INCY'  1  1
  'SCALAR'     2.5
  'VECTOR X'   2.0  4.0  6.0  8.0
  'VECTOR Y'   5.0  -3.0  -12.0  4.0
  'RESULT Y'   10.0  7.0  3.0  24.0
.sp2
  XXX
.DE
.fi
.sp1
These three examples could be in one file.  As a file, there would be three
separate test cases which would be executed during one run.  The first test
case is a test for SASUM, the second for SDOT, and the third for SAXPY.
     The first two lines of each test case are formatted.  The first field
consists of 31 characters containing the name of the SCIPORT routine that is
to be tested.  The next field of 5 characters is an identification code which
should be unique since it is listed for output when an error occurs on that
particular test.  The next field is 8 characters and contains the date that
the test case was entered into the file.  Then there is a 5 character field
which contains the initials of the person that created the test case.  This
is followed by an 8 character field which contains the date that the tests
were run to put results into the file.  This date is written by the computer
on which the test is run at runtime.  The last field on the first
line is 23 characters and is reserved for comments on what condition the
specific test case was set up to test.
     The second line contains one 30 character field which is read from a data
file during execution.  It contains information on the specific CRAY software
that was used to generate CRAY SCILIB results, which get inserted into the data
file.  This information might include anything that would distinguish one CRAY
from another, such as the type of CRAY (e.g. CRAY-1, CRAY X-MP),
the version of the operating system, the version of the FORTRAN compiler, etc.
     After the first two lines, each additional line is free-field formatted.
The first field on each line must be a string enclosed in single quotes, and
should not exceed ten characters in length.  Any fields following the first
are numeric and contain the numeric data described by the character string
of the first field.
     Now, to add a new test case, edit the data file that includes the routine
to be tested, find a test case that already exists for that particular routine,
copy its format, and add it to the end of the file, just before XXX, since the
identification codes for the tests that already exist are numbered
sequentially.  Once a new test case is added, the test procedure(s) for the new
case(s) must be run on the CRAY to get the CRAY results.
For information on how to do a run on the CRAY, consult the VAX/CRAY
Interface report [4].  In order to run the test procedure(s),
assignments must be made to the appropriate FORTRAN logical unit numbers.  The
numbers can be found in the documentation at the beginning of the test drivers.
Only one driver from each group of routines is needed to do a run on the CRAY
(the CRAY gives the same results regardless of precision),
therefore, it is suggested that the double precision drivers be used since
they provide more accuracy in formatted output than the single precision
drivers.
Once the CRAY results are available, the tests can now be run on the VAX.  If
there is an error in the new test case, or any previous ones, a message will be
printed to logical unit 6 (screen) for each error.  The message includes
the identification code for any test case that failed, which makes it easier to
locate the case for which the error occured.
.sp1
.bp
.ce 1
.ul 1
BIBLIOGRAPHY
.RL
.LI
CRAY-1 Computer Systems Library Reference Manual,
     SR-0014; CRAY Research, Inc., 1982.
.LI
LINPACK User's Guide;  J.J. Dongarra, C.B. Moler,
     J.R. Bunch, and G.W. Stewart; Society for
     Industrial and Applied Mathematics, Philadelphia,
     1979.
.LI
Matrix Eigensystem Routines - EISPACK Guide, second
     edition; B.T. Smith, J.M. Boyle, J.J. Dongarra,
     B.S. Garbow, Y. Ikebe, V.C. Klema, C.B. Moler;
     Springer-Verlag, New York, 1977.
.LI
VAX/CRAY Interface System: A Solution to Compute-Bound
     Problems; S.H. Lamson and F.S. Eddy, Information
     System Operation; General Electric CRD, Schenectady,
     New York; TIS Report No. 84CRD132, June 1984.
.LI
     The documentation provided by Cray Research, Inc.
in their CRAY-1 Computer Systems Library Reference
Manual, SR-0014, has been reproduced in part here
and in the SCIPORT on-line help facility with their
consent.
.LE
.TC 2 1 3 0

--------



.
