SCIPORT (3sciport)

An Alpha specific version of SCILIB

DESCRIPTION

  SCIPORT is a Compaq Equipment Corporation implementation of CRAY SCILIB.
  SCIPORT provides 64 bit single precision library routines for CRAY users
  porting programs to Alpha systems running Compaq Tru64 UNIX.

  SCIPORT is quite comprehensive. All CRAY Math Library and CF77 (CRAY
  FORTRAN) Math intrinsic routines accessible from high level languages are
  available to users porting programs from CRAY systems. Many are available
  in 64 bit and 128 bit forms directly from Compaq FORTRAN and plug compatible
  with their CF77 counterparts. SCIPORT complements Compaq FORTRAN by providing
  those math routines which are not available as Compaq FORTRAN intrinsics. In
  some cases, users may have to modify code slightly to declare the data
  types of these functions.

  Additionally, SCIPORT provides true 64 bit versions of all CRAY SCILIB
  single precision BLAS-1, BLAS-2, and BLAS-3 routines; all CRAY SCILIB
  LAPACK routines; all CRAY SCILIB Special Linear System Solver routines; all
  CRAY SCILIB Signal Processing routines; and all CRAY SCILIB Sorting and
  Searching routines. The routines listed are plug compatible with their CRAY
  SCILIB counterparts and with the exception of the ORDERS routine, require
  no program changes to function correctly. Owing to endian differences of
  machine architecture, special considerations must be given when ORDERS is
  used to sort multi-byte character strings.

  SCIPORT also provides some non-math CF77 intrinsic functions. For example
  conditional vector merge (CVMG*) functions are offered. Many of these CF77
  intrinsic functions return a CF77 data type of Boolean, which is not
  supported by ANSI FORTRAN-77. Users of these functions must carefully
  ensure that the functions are declared with the type of the target output.
  SCIPORT versions of these routines accept all data types as input and treat
  the output as an unsigned 64 bit integer. Great care was taken in the
  development of SCIPORT to minimize compatibility issues. In many cases,
  SCIPORT routines provide bit for bit compatible results. The SCIPORT
  version of RANF, for example returns exactly the same sequence of random
  digits as its CRAY SCILIB counterpart.

  Many SCIPORT routines call into the CXML, which must be installed prior to
  installing SCIPORT.  The link line must include libcxml, linked
  after the SCIPORT library.

  SCIPORT is easy to use. Once a ported CF77 program compiles cleanly, the
  following Fortran command is all that's needed to bind it to SCIPORT:

       > fortran -o prog -r8 -i8 -double_size 128 prog.f -lsciport -lcxml


  To avoid the cumbersome inclusion of required fortran switches, Compaq
  strongly urges SCIPORT users to define and use a shell command alias such
  as the one shown below:

       > alias cf77 'fortran -r8 -i8 -double_size 128'

  Using the command alias shown above, SCIPORT may be used by the command
  line shown below:

       > cf77 -o prog prog.f -lsciport -lcxml

BLAS

  Users of the SCIPORT BLAS routines are asked to reference CXML for their
  documentation needs. The SCIPORT BLAS routines are identical to the CXML
  single precision real and complex BLAS routines - with the following
  exceptions. All references to integer*4 should be changed to integer; all
  references to real*4 should be changed to real; and all references to
  complex*8 should be changed to complex. SCIPORT BLAS routines expect and
  use only 64 bit integer and floating point data types.

FFT

  Fast Fourier Transforms --- a group of subprograms that apply a fast
  Fourier transform and compute either a Fourier analysis or a Fourier
  synthesis.

			---------- Warning ------------

  For performance reasons, SCIPORT uses three step CXML FFT routines. The
  three step CXML FFT routines require users to supply a structure which is
  used by the FFT routine. These FFT structures may not be overwritten by
  users between FFT calls. To do so will introduce memory leaks. CRAY FFT
  routines require users to supply work areas. Depending on which CRAY FFT
  routine is used, these work areas may or may not be overwritten between
  calls.

			-------------------------------


  To minimize the effort required to port a program from a CRAY system to a
  Compaq Alpha system, SCIPORT maintains the same user FFT interface. To do
  so, SCIPORT overlays a user supplied work area with the requisite CXML
  structure. Although this technique does preserve the user calling
  interface, it also introduces two operational problems.

  1. For very short FFTs, the size of the workspace (in 64 bit words)
  required on the CRAY system may be smaller than the size of the work space
  required by the underlying CXML routine. In most cases the actual size of
  the work space cannot be detected from within the FFT, and so it cannot be
  checked. This problem is addressed in the man pages. The man page for each
  SCIPORT FFT routine now specifies a minimum size required for each
  workspace.

  2.  Some CRAY FFT routines permit their workspaces be overwritten
  between FFT calls. Overwriting a SCIPORT FFT workspace overwrites pointers
  within the CXML structure, causing  malloc'd data to be forever orphaned -
  a memory leak. The problem is difficult to detect and solve from within
  SCIPORT, and may require active user intervention. To assist in the porting
  effort, the man pages for each SCIPORT FFT routine now identify which work
  area gets overlaid. Once a user knows which work area is used by SCIPORT,
  measures can be taken to avoid writing to that area between FFT calls.

  PLEASE NOTE 
  IF YOUR PROGRAM USES A CORRECTLY SIZED WORKSPACE, DEDICATED
  FOR USE BY A GIVEN FFT ROUTINE, YOU CANNOT HAVE THE SECOND PROBLEM AND YOUR
  PROGRAM SHOULD PORT WITHOUT MODIFICATION.

  For users who cannot guarantee dedicated FFT workareas, escape mechanisms
  are provided for each FFT routine. The escape mechanisms permit users to
  free CXML FFT structures and avoid memory leaks. Each escape mechanism is
  designed to use a form of the FFT call which will be ignored by a CRAY
  system, in the event that the modified program should be ported back.

FILTERS

  A group of subprograms used for filter analysis and design.  They can also
  be used to solve more general problems.

LINEAR_RECURRENCE

  A group of 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.

SEARCH

  A group of 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.