Digital Extended Math Library (DXML) Version 3.3A for Digital UNIX Release Notes January, 1997 1 Purpose of Release Notes These release notes provide information about the DXML Version 3.3A release. DXML Version 3.3A is identical to DXML Version 3.3 with one exception as follows. The installation scripts for the par- allel development subset (XMDPLL330) and the run-time subset (XMRPLL330) have a too restrictive test that causes the wrong version of the library to be installed on some newer, yet to be released versions of Digital UNIX. The error causes the IVP to fail and the library not to work. DXML Version 3.3A fixes the problem. 2 DXML Distribution DXML is distributed in two different forms: 1. The DXML Version 3.3A Development Kit allows you to link an application program with the DXML library and then run the executable image. The License Management Facility (LMF) name for the development option is EXT-MATH-LIB. The kit includes the following subsets: o XMDLOA331 - includes shared library, archive library, release notes, Installation Verification Procedure (IVP), examples, and various DXML utilities. o XMDMAN331 - includes the DXML manpages. o XMDPLL331 - includes shared library for the parallel ver- sion of the library and the parallel version of the IVP. This subset should only be installed on SMP configurations running Digital UNIX Version 3.0 or later. o XMDSCI331 - includes the SCIPORT archive library and manpages 2. The DXML Version 3.3A Run-Time Kit allows an executable image that has been linked on a different system to be executed on the target system. The LMF name for the run-time option is EXT-MATH-LIB-RT. The kit includes the following subset: o XMRLOA331 - includes the run-time version of the serial shared library, release notes, and IVP. o XMRPLL331 - includes the run-time version of the parallel shared library and the parallel version of the IVP. Install either the development kit or the run-time kit on your system - never both. The DXML Version 3.3A distribution kit includes versions of the library optimized for EV5 and versions optimized for EV4. The installation script will determine what system it is running on and then prompt the installer with one of the following two questions: Do you want to install the EV5 library [y]? or Do you want to install the EV4 library [y]? Pressing the carriage return or y keys will always install the EV5 library on an EV5 system, and the EV4 library on EV4 systems. Only one library will be installed. It is possible to override the default, but it is not recommended. 3 Changes Since Last Release The previous DXML Version 3.2 was released in January 1996. 3.1 Skyline Solver The DSSKYF and DUSKYF routines have been parallelized for all storage modes. The driver routines, both simple and expert, that use these factorization routines will also see a speedup. A bug in the solver routines for problem sizes less than 12 has been fixed. 3.2 Signal Processing All FFT subroutines, except group FFT, have been revised to significantly improve their parallel performance. 3.3 SCIPORT SCIPORT has been added to DXML with this release. SCIPORT is a Digital Equipment Corporation implementation of CRAY LibSci. SCIPORT provides 64 bit, single-precision library routines for CRAY users porting programs to Alpha systems running Digital UNIX. SCIPORT makes available to users porting programs from CRAY systems almost all CRAY Math Library and CF77 (CRAY FORTRAN) Math intrinsic routines. Additionally, SCIPORT provides the following: o True 64-bit versions of all CRAY LibSci single-precision BLAS-1, BLAS-2, and BLAS-3 routines o All CRAY LibSci LAPACK routines o All CRAY LibSci Special Linear System Solver routines o All CRAY LibSci Signal Processing routines o All CRAY LibSci Sorting and Searching routines 2 These routines are completely interchangeable with their CRAY LibSci counterparts and, with the exception of the ORDERS rou- tine, require no program changes to function correctly. Owing to endian differences of machine architecture, special consid- erations must be given when the ORDERS routine is used to sort multibyte character strings. SCIPORT also provides some nonmath CF77 intrinsic functions. For example conditional vector merge (CVMG*) functions are offered. Many of these CF77 intrinsic functions return a CF77 Boolean data type not supported by ANSI FORTRAN-77. Users of these functions must 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 identical results. The SCIPORT version of RANF, for example, returns exactly the same sequence of random digits as its CRAY LibSci counterpart. After you install the optional SCIPORT subset XMDSCInnn, SCIPORT is easy to use. For example, once a ported CF77 program compiles without error, you link it to SCIPORT by using the following sample f77 command: > f77 -o prog -r8 -i8 -double_size 128 prog.f /usr/lib/libsciport.a To avoid the cumbersome inclusion of required f77 switches, Digital strongly urges SCIPORT users to define and use a shell command alias such as: > alias cf77 'f77 -r8 -i8 -double_size 128' After using the command alias, you can use SCIPORT by issuing the following command: > cf77 -o prog prog.f /usr/lib/libsciport.a 3.3.1 SCIPORT BLAS Users of the SCIPORT BLAS routines should reference DXML for their documentation needs. The SCIPORT BLAS routines are iden- tical to the DXML single-precision, real, and complex BLAS routines with the following exceptions: o All references to integer*4 should be changed to integer. o All references to real*4 should be changed to real. o All references to complex*8 should be changed to complex. SCIPORT BLAS routines use only 64 bit integer and floating point data types. 3 3.3.2 SCIPORT FFT The SCIPORT FFT subprograms apply a fast Fourier transform to compute either a Fourier analysis or a Fourier synthesis. 3.3.3 SCIPORT Filters SCIPORT filter subprograms are used for filter analysis and design. They can also be used to solve more general problems. 3.3.4 SCIPORT Linear Recurrence A linear recurrence is a term-by-term evaluation of a quantity based on initial values and previously computed values. SCIPORT subprograms solve first-order and some second-order linear recurrences. 3.3.5 SCIPORT Search SCIPORT search subroutines find the following: o the number or positions of true occurrences within a vector o the first occurrence of a target object within a vector o the indices of all positions of an object within a vector o targets within ordered arrays 3.3.6 SCIPORT Documentation For information about SCIPORT, see these release notes and the online manpages. For example, for general information about SCIPORT, use the command > man sciport. For information about a SCIPORT routine, use > man routine_name, where routine_name is the name of a SCIPORT routine. 3.4 DXML Sort Routines Two quick sort and two general purpose sort subprograms have been added to DXML with this release as follows: o {I,S,D}SORTQ sorts elements of a vector using the quick sort algorithm. o {I,S,D}SORTQX sorts an indexed vector of data for integer using the quick sort algorithm. o GEN_SORT is a general purpose, in memory, sort routine. o GEN_SORTX is a general purpose, in memory, indexed sort routine. For information about the DXML sort routines, see the DXML Reference Manual and the online manpages, for example, > man sorts. 4 3.5 DXML Random Number Generators DXML provides four random number generator (RNG) subprograms and two auxiliary input subprograms for parallel applications as follows: o RANL produces a vector of uniform [0,1], long period random numbers. o RANL_NORMAL produces a vector of N(0,1), normally distributed random numbers. o RANL_SKIP64 is an auxiliary input program for parallel appli- cations using RANL and RANL_NORMAL. o RANL_SKIP2 is an auxiliary input program for parallel appli- cations using RANL and RANL_NORMAL. o RAN69069 uses a linear multiplicative algorithm to produce single-precision random numbers. o RAN16807 uses a Lehmer multiplicative generator to produce single-precision random numbers. For information about the DXML random number generator routines, see the DXML Reference Manual and the online manpages, for example, > man random-numbers. 4 Kit This version of DXML was built on Digital UNIX V3.2C (rev 148) using Digital Fortran Version 4.0-1, DEC C Version 5.0-106, and KAP for DEC Fortran Version 3.0 with libkmp_osf.a (bl26.2) and libkmp_osfp10.a (bl27.2). We have changed the installation script for the run-time library to prevent installation of the run-time kit in the event the development kit is already installed. To allow this version of DXML to work on both Digital UNIX Versions 3.2 and 4.0, we have changed the installation scripts. The scripts determine if the system is version 3.2 or 4.0 and then build the corresponding shared library as part of the installation. This change is motivated primarily by the changing threads libraries. IMPORTANT If you upgrade the operating system from Digital UNIX Ver- sion 3.2 to Digital UNIX Version 4.0, you must reinstall DXML. 5 User Documentation The DXML Reference Manual and Installation Guides have been updated for this release. Two new chapters, one for random number generator subprograms and one for sort subprograms, have been added. 5 6 Digital UNIX Version 4.0 To use DXML on Digital UNIX Version 4.0, you may need to make a few minor changes to your system environment including the following: o You may have to increase the limits of some system resources, as displayed with the limit command. Alternatively, you can issue the unlimit command before you execute your program. o You may have to increase the system parameter vm-vpagemax which sets the maximum number of virtual pages within the address space of one process. The default value for the vm-vpagemax parameter is 16384. The default value is not large enough for many technical and scientific applications. Consequently, Digital suggests you increase the vm-vpagemax parameter to a value equal to the size of available memory divided by 8. For example, on a 2 gigabyte system, set vm- vpagemax to 262144. After you change vm-vpagemax, you must reboot your system for the new value to take effect. 7 Installation Verification Procedure (IVP) Because of a possibly too low default setting for the system parameter vm-vpagemax, the IVP for the parallel library may fail. In this event, increase the value for vm-vpagemax as explained in Section 6. 8 Reporting Problems and Comments to Digital Comments or problem reports on DXML can be sent to dxml@hpc.pko.dec.com. The DXML developers welcome your feedback. AlphaGeneration, AlphaServer, Bookreader, and the DIGITAL logo are trademarks of Digital Equipment Corporation. KAP is a trademark of Kuck & Associates, Inc. UNIX is a registered trademark in the United States and other countries licensed exclusively through X/Open Company Ltd. CRAY is a registered trademark of Cray Research, Inc. ©Digital Equipment Corporation. 1996. All Rights Reserved. 6