PORT MATHEMATICAL SUBROUTINE LIBRARY TABLE OF CONTENTS Chapters

PORT library Contents May 1, 1997

PORT MATHEMATICAL SUBROUTINE LIBRARY

TABLE OF CONTENTS

Introduction

Chapters

Framework

Approximation, Interpolation and Extrapolation

Differential Equations

Linear Algebra and Eigensystems

Optimization and Mathematical Programming

Partial Differential Equations

Quadrature and Differentiation

Roots

Special Functions

Transforms

Utility

Program Cross-Reference

Program-Chapter Index

Permuted Index

PORT library

May 1, 1997

INTRODUCTION TO PORT 3

1. THE THIRD EDITION OF THE PORT MATHEMATICAL SUBROUTINE LIBRARY

One of the original interpretations of the acronym,PORT, for the library of Fortran mathematical subrou-tines presented here was the set of speci?cations: Portable, Outstanding, Reliable and Tested. These aims indeed govern the development of the library; the numerical algorithms are selected with care and their im-plementations are carried out with attention to robustness, accuracy and ef?ciency.

PORT is a licensed product of AT&T Bell Laboratories. For a number of years it has been in use on a wide variety of computer types, both inside the labs and at other sites. Primary consideration has always been given to making the library portable, and indeed only one version of the library tape is maintained. Installa-tions of the library from this tape have been made on such disparate machines as the APPLE I I computer and the CRAY-1. Reference [ 1 ] contains further information on the library and its development.

Scope

The PORT library takes as its province mainly the traditional areas of mathematical software, but it does not include statistical routines. In fact for several areas, whenever we feel there are already excellent libraries available in the public domain, e.g. EISPACK [ 3 ], or QUADPACK [ 4 ], or the Collected Algorithms of the ACM [ 5 ],PORT does not duplicate the work. We offer mainly programs that have been developed at AT&T Bell Laboratories and have proved their value over the years in solving problems posed by members of our technical staff. In a few cases programs from the public domain have been adapted to PORT for the bene?t of our users. The adaptations have always been done only with the concurrence of the original au-thors, and include the PORT routines EIGEN (which calls on three EISPACK routines), Richard Brent’s FMIN and ZERO routines, the Jenkins-Traub polynomial root ?nders, Richard Singleton’s Fast Fourier Transform and David Sookne’s Bessel function routines. Detailed references are provided in the program reference sheets for these programs.

The principal non-numeric subroutines in PORT are the programs for error-handling, memory stack alloca-tion, and machine-constant speci?cation. These constitute the "Framework" of the library. They have ap-peared as ACM Algorithm 528 [ 2 ], and are described in the Framework chapter in the following documen-tation. The capabilities they provide have proved to form a convenient setting for program development;

they are used extensively within the labs, and have been applied to the development of various packages de-veloped elsewhere as well.

Introduction PORT library

May 1, 1997

Installing PORT

Information on licensing PORT can be obtained by writing to the Supervisor of the Computing Information

Service at AT&T Bell Laboratories, Murray Hill, NJ 07974.

An installation manual is provided along with the tape containing the Fortran source for the library. In gen-

eral, depending on the speed of your compiler, it takes very little time to put up the library. One has only to

choose the appropriate machine dependent constants in the three functions used for machine-constant

de?nition, and then compile the source. The tape includes test programs and also a ?le of the small exam-

ple programs found in the program reference sheets in this manual.

2. HOW TO USE THIS MANUAL

Each chapter of this manual is devoted to one principal area of the library. For each chapter an introductory

section discusses appropriate applications for the various routines in the chapter. Documentation for the in-

dividual subroutines has been kept as brief as possible, while still providing enough information to enable

their use. Information on additional references has been included whenever such material is available.

The descriptions of the subroutines are ?led alphabetically within each chapter. Single-precision subpro-

grams are given names with at most ?ve alphanumeric characters so that the double-precision version can

add a ‘D’ at the front, as in ZERO and DZERO. The single-precision version is documented, with notes

added for any special double-precision attributes of the program.

In the de?nitions of the parameters in the calling sequence for a routine the input parameters are shown

with an arrow facing to the right, and the output parameters with an arrow facing to the left. E. g.

N→size of the system

ANS←resulting solution

If a parameter is used for both input and output, separate arrows and de?nitions are given.

How to ?nd the program you want

There is a permuted index, sometimes known as a KWIC index, at the end of the manual. This is the best

place to start. Look in the center column for the topic of interest to you, and ?nd the name of the appropri-

ate program and the chapter in which it is to be found.

A number of other indexes are included in the index section of the manual for the convenience of the user.

There is a Program-Chapter Index that lists all the (documented) programs alphabetically along with a one-

line description of what they do, and the name of the chapter in which they are to be found. There is a PORT

program library cross reference detailing the structure of the library by giving the names of the programs

calling or called by any particular subroutine. You may notice in the cross reference some routines which

are not documented in the earlier material. These are lower-level routines usually with somewhat exotic

PORT library Introduction May 1, 1997

names, e.g. I8TSEL. The naming convention used in PORT speci?es that undocumented routines should

have a digit as the second character of their name, to help avoid name con?icts. The current edition of

PORT has some exceptions to this rule, and in any case it is always wise to check the cross-reference to

avoid name con?icts. Another index lists PORT programs using named (labeled) COMMON regions and

gives the names used. The convention for naming COMMON regions is to use digits for the second and

third characters of the name. The corresponding region for the double-precision version of the program

uses the same name preceded by a ‘D’. (Some of the older programs in the library do not adhere to this

naming convention.)

The Framework?error handling and the storage stack

The introductory section to the Framework chapter of the manual discusses error handling and dynamic

storage stack allocation in PORT.

Since error handing is done in a centralized manner, at ?rst shot you may not want to read about it, but

again, when you get to the point that you want to recover from a class of errors known as ‘recoverable’ er-

rors, you should read the Framework discussion.

Similarly, since PORT’s use of a dynamic storage stack (simulated in a named COMMON region) for tem-

porary storage is done internally and is not visible to the user, you don’t have to know about it, but in time

you may want to learn about it and use its capabilities. Also, if a run aborts and you get a stack dump, you

may want to know more about it.

Language

The programming language of PORT is the particular subset of Fortran 66 speci?ed by the PFORT Veri?er

[ 6 ]. (See also [ 7 ], [ 8 ], and [ 9 ].) Library programs are always sent through the Veri?er to guarantee their

adherence to this language requirement. We have used this skeletal form of Fortran to achieve the widest

possible portability, and we have not found that it has introduced penalties either in performance or upward

compatibility to Fortran 77. In fact we have compiled PORT successfully under several Fortran 77 compil-

ers, including the IBM VS Fortran.

However, two assumptions were made about Fortran 66, that seem valid for most production systems. First

it is assumed that there is no subscript range checking. Second it is assumed that variables local to a sub-

program which are initialized by DATA statements retain their values from one subprogram invocation to

the next.

No use is made of character data in PORT’s Fortran; the error messages are stored as integer variables. Also,

since Fortran 66 limits us to a ?xed array size at compilation, subroutines are compiled with a default di-

mension of 500 double-precision locations in the dynamic storage stack. To adhere to a strict interpretation

of the Fortran 66 Standard [7, Section 10.2.5 ] in using the dynamic storage stack, it is necessary in the

main program to declare the COMMON region CSTAK. These precautions will ensure that data stored in

the stack will not be lost when using overlays (segments) or when running under Fortran systems in which

COMMON is dynamically allocated. If a larger stack is required, the subroutine ISTKIN (documented in

the Framework chapter) must be called in the main program to increase the stack size. This approach has

Introduction PORT library

May 1, 1997

worked correctly in all the compilers we know about.

We have found that PORT compiles and runs successfully under most Fortran systems from very large sys-

tems (e.g.CRAY-1) to very small systems (e.g.APPLE I I).

ACKNOWLEDGMENTS

Over the almost ten years of PORT’s existence a great many people have contributed to its development.

They have provided programs, advice, and encouragement, and without them there would have been no

PORT. They include James L. Blue, W. Stanley Brown, William M. Coughran, Jr., David M. Gay, Alan M.

Gross, Eric H. Grosse, Andrew H. Hall, Linda Kaufman, Wesley P. Petersen, Norman L. Schryer, and

Daniel D. Warner. Then there are the many users at sites and ports from Australia all the way eastward to

Taiwan, and including AT&T Bell laboratories. We appreciate all of their suggestions.

Phyllis Fox

AT&T Bell Laboratories,

Murray Hill, NJ

May 8, 1984

PORT library Introduction

May 1, 1997

REFERENCES

[ 1 ] Fox, P.A., Hall, A.D., and Schryer, N.L. The

PORT Mathematical Subroutine Library,ACM Trans.

Math. Software 4, 2 (June 1978), 104-126.[ 2 ] Fox, P.A., Hall, A.D., and Schryer, N.L. Algorithm 528: Framework for a Portable Library,ACM

Trans. Math. Software 4, 2 (June 1978), 177-188.

[ 3 ] Smith, B.T., et al.,Matrix Eigensystem Routines ?EISPACK Guide.Springer-Verlag, New York,

2nd ed., 1976.

[ 4 ] Piessens, R., de Doncker-Kapenga, E., U . .berhuber, C., and Kahaner, D.,QUADPACK, A Subroutine

Package for Automatic Integration , Springer Series in Computational Mathematics, No. 1, 1983.

[ 5 ]

Collected Algorithms from ACM , Association for Computing Machinery, Inc., 1133 Avenue of the

Americas, NY, NY 10036, ongoing publication.[ 6 ] Ryder, B.G., The PFORT Veri?er,Software Practice and Experience 4, 4, (October-December

l974), 359-377.

[ 7 ]

USA Standard Fortran,USA Standards Institute, New York, N. Y. 1966.[ 8 ] Clari?cation of Fortran Standards - Initial Progress,Communications of the Association for Comput-

ing Machinery 12, (1969), 289-294.

[ 9 ]

Clari?cation of Fortran Standards - Second Report,Communications of the Association for Comput-

ing Machinery 14, (1971), 628-642.

PORT library

May 16, 1984

Note on the third edition of PORT

Those who are familiar with the second edition of the Mathematical Subroutine Library,PORT, will know that it contained subroutines for solving differential equations, for integrating integrals involving even noisy integrands or integrands with a singularity, and spline routines for interpolation, integration, and dif-ferentiation. There were routines for ?nding the zeros of systems of nonlinear equations, and, for ?nding the roots of polynomial, the Jenkins-Traub algorithm was provided. P ORT2 included a portable random number generator for uniformly distributed variates, guaranteed to produce the same sequence of values, to the accuracy of the computer, on any computer with 16 or more bits per word. Singleton’s algorithm for Fast Fourier Transforms was included, and there were various routines for evaluating special functions. In general, the routines represented the state of the art in the areas covered. However there were gaps, espe-cially in the linear algebra and optimization areas, and these have been ?lled in our new edition of the li-brary.

P ORT3, which is perhaps twice as big as PORT2, adds several new packages of routines:

The linear algebra chapter contains over three hundred new subroutines for solving linear systems. There are routines for solving general systems (including complex systems), banded systems, banded positive de?nite systems, and symmetric systems. There is also a suite of subprograms for solving sparse systems.

All the routines have been written by Linda Kaufman.

The optimization chapter provides routines for a variety of optimization tasks such as nonlinear least squares (including separable nonlinear least squares), and general nonlinear optimization. Both uncon-strained versions and versions with simple bounds are included. Subroutines for linear and quadratic pro-gramming are also there. These routines have been written by David Gay and Linda Kaufman.

P ORT3 adds a new chapter containing the package "POST" written by Norm Schryer for solving sets of time-dependent partial differential equations in one space dimension. The systems can be coupled to ordi-nary time-dependent differential equations, facilitating the tracking of moving boundaries, such as shocks, or permitting the user to specify global (as opposed to boundary) conditions on the variables.

In the differential equation chapter there is a new robust routine, IODE, also written by Norm Schryer, for integrating stiff systems.

For the transforms chapter, Wes Petersen has written a new group of subroutines for doing self-sorting mul-tiple Fast Fourier Transforms to compute a number of independent transforms simultaneously.

In the approximation chapter there are three new subprograms, written by Eric Grosse, for doing ?tting with uniform variation-diminishing spline ?ts. These are provided for ?tting in one, two, and three dimensions.

The quadrature chapter has several new Gauss quadrature routines for various weights and ranges, based on the appropriate orthogonal polynomials. These were written by Jim Blue, who is now at the National Bu-reau of Standards.

The utility chapter has several new subroutines. There is a subprogram for printing the PORT dynamic stor-age stack, written by Dan Warner (now at Clemson University). This stack dump, which is helpful for de-

PORT library

May 16, 1984 bugging, needs to compute the correct machine-dependent Fortran formats for printing integers, reals, etc.,

?it computes these using the PORT machine constants?which it then uses in array-printing routines. We

have made these output subroutines available to the user; they are described in the "Utilities" chapter.

Single-precision and double-precision versions of all the routines (where appropriate) have been provided,

and documentation is given for the single-precision version, with notes indicating any special aspects of the double-precision version.

Phyllis Fox

AT&T Bell Laboratories

600 Mountain Avenue

Murray Hill, New Jersey 07974