Algorithm xxx: Quadruple-Precision $\Gamma(x)$ and $\psi(x)$
                Functions for Real Arguments

                             by

                     Nelson H. F. Beebe
                            and
                       James S. Ball

                     University of Utah

                       [31-Jul-2000]
                   Revised: [15-Dec-2000]

=================
Table of Contents
=================

        Introduction
        Before you start
        Installation
        IBM RS/6000 and SGI systems
        Non-IEEE 754 systems
        Non-POSIX-conformant operating systems
        How the tests work
        Plotting the tests
        Arithmetic-system-dependent constants
        Bug and problem reports
        Copyright issues
        Distribution contents
        Manual builds, or, doing it the hard way


============
Introduction
============

The software in this package is described in detail in the
extensive article

@String{j-TOMS                  = "ACM Transactions on Mathematical Software"}

@Article{Beebe:2000:AXQ,
  author =       "Nelson H. F. Beebe and James S. Ball",
  title =        "Algorithm \emph{xxx}: Quadruple-Precision $\Gamma(x)$
                 and $\psi(x)$ Functions for Real Arguments",
  journal =      j-TOMS,
  volume =       "26",
  number =       "??",
  pages =        "??--??",
  month =        "????",
  year =         "2000",
  CODEN =        "ACMSCU",
  ISSN =         "0098-3500",
  bibdate =      "Sat Dec 11 16:13:53 1999",
  acknowledgement = ack-nhfb,
}

This directory contains the test programs and data for
checking the accuracy of the Gamma(x) and psi(x) functions
provided in ../common in single-, double-, and
quadruple-precision floating-point arithmetic.

Tests are also included for the Fortran intrinsic functions
cos(x), exp(x), log(x), sin(x), and tan(x), because they are
needed in Gamma(x) and/or psi(x).

You should NOT assume that your Fortran implementation
provides accurate versions of these intrinsics.  Extensive
testing documented in the above article revealed several
cases where these intrinsics are inaccurate, and sometimes,
just plain wrong!


================
Before you start
================

Analysis of the numerical tests will be made vastly easier
if you already have the first author's ndiff utility
installed.  This is expected to be described in an article
in ACM Transactions on Mathematical Software, and after
publication, the code will be available from
ftp://ftp.netlib.org/toms and http://www.netlib.org/toms.
In each case, it will be in a subdirectory identified by its
algorithm number.

Because there is normally some delay in netlib archiving,
a prerelease of this software is available at the first
author's Web site:

        http://www.math.utah.edu/~beebe/software/ndiff

Because there are about 500,000 numeric function values in
the test/okay/*.out files, it is in practice infeasible to
evaluate the output of "make check" if you use diff instead
of ndiff: there could be MILLIONS of lines of differences
reported.


============
Installation
============

As with most GNUware, you can build, test, and install this
program on most UNIX and POSIX-compliant systems by these
simple steps:

        env F77=Fortran-compiler-name ./configure && make -i all check install

Because the tests may reveal problems, "make"'s -i flag is
used to get nonstop behavior.

Please note that due to an irregularity in GNU autoconf, the
Fortran compiler name variable is F77 at "configure" time, but
FC at "make" time.  While I could repair this locally to
remove the inconsistency, the correction would be lost if
autoconf were run again at an end-user site.  At present,
GNU autoconf lacks a maintainer, so it is unknown when, or
if, this flaw in autoconf may be repaired.

You can set compiler optimization levels through the COPT
and FOPT variables on the "make" command line, for C/C++ and
Fortran respectively:

        make COPT=-xO3 FOPT='-xO5 -g3' targets...

You can let "configure" pick a default Fortran compiler by
simply doing

        ./configure && make -i all check install

It will then search for the first one found in this list:

        f77 g77 f90 f95

The code has been written very carefully to work under any
Fortran compiler conforming to ANSI/ISO Fortran 77, 90, 95,
or High-Performance Fortran.  Fortran 66 is NOT supported.

Some Fortran 90 and 95 compilers assume free-form source
format by default, in which case they need an extra flag to
revert to fixed-form source format.  "configure" will supply
this flag automatically where necessary for compilers on the
test systems at the development sites.  Most such compilers
more sensibly automatically assume fixed-form source format
for source file extension .f, and free-form format for
extensions .f90 and .f95.

At present, "make install" in this directory does not do
anything, but the target is included because it is a GNU
standard.  You will likely want to do "make install" in
../common or in .. .

If you wish to undo a "make install", just do "make
uninstall"; this will remove any files in system directories
put there by "make install".

Because not all Fortran implementations provide
quadruple-precision arithmetic, the default "make all check"
EXCLUDES builds and tests of the quadruple-precision
software.  You need to do "make all-qp" and/or "make
check-qp" to override this for systems with full 128-bit
quadruple precision, and "make check-qp-double" for those
(IBM and SGI: see below) with paired-double quadruple
precision.

You can build and/or test just one precision with the
targets all-dp, all-qp, all-sp, check-dp, check-qp (or
check-qp-double), and check-sp.  Look in the Makefile to see
how these further cascade into tests of specific functions
with particular groups of test data, making it easy to
repeat a particular test that has failed, after a build with
a different compiler, or different compiler options.


===========================
IBM RS/6000 and SGI systems
===========================

As described at length in the article, these two
architectures have a different representation of
quadruple-precision than others: they use a pair of doubles
instead.  This changes several machine constants in *.inc
and ../common/*.inc.  As shown in the article, patches can
be easily, and RELIABLY, applied with the GNU patch utility:

        patch < ibmsgi.pch

You can revert to the original versions by reversing the patch:

        patch -R < ibmsgi.pch

cIf you do not have patch installed, don't waste time making
the changes manually: fetch and install patch from its
distribution at

        ftp://ftp.gnu.org/gnu/patch

These patches MUST be applied before you can build
correctly-functioning versions of this software on the IBM
RS/6000 and SGI architectures!  Unlike C, Fortran lacks a
standard preprocessing facility, so we could not include both
versions of constants in one source file.


====================
Non-IEEE 754 systems
====================

The only significant non-IEEE 754 floating-point
architectures still in use in the year 2000 are:

        Compaq/DEC VAX
        Cray X-MP, Y-MP, C90
        IBM S/360

VAX systems will no longer be shipped after September 2000,
according to the vendor Web site at

        http://www.compaq.com/AlphaServer/vax/vax_now.html

Cray systems with non-IEEE 754 arithmetic are becoming
rarer.

IBM S/360 systems are common, but in 1999, IBM announced the
S/390 G5 processor with full support (in hardware) of
single-, double-, and quadruple-precision IEEE 754
arithmetic.  I suspect that older S/360 processors will
enjoy IEEE 754 support in software, if the compilers are
recent, so switch to it if possible, and leave the source
code of this package unchanged.

You will need to change machine constants in the *.inc and
../common/*.inc files according to the recipes documented in
their comments.  You will also likely need to change some,
or all, of the test data files, test/*.in, because the
ranges of numbers that they generate are chosen to match
IEEE 754 arithmetic, and the various approximation regions
used in the function evaluation.


==================
How the tests work
==================

The numeric tests performed by "make check" collect results
from your system in the files test/*.out.  These are then
compared using ndiff (if available), or diff (if not) with
high-precision (50 decimal digit) values in the
corresponding test/okay/*.out files.


==================
Plotting the tests
==================

The Makefile includes targets named plot-relerr-* for
producing plots of the relative errors, similar to most of
the figures in the published article.  These are MUCH better
at revealing problems than the simple numerical reports
produced by "make check" and ndiff.

In order to use these targets, you need two other
significant packages:

        Maple (a commercial product):   http://www.maplesoft.com/

        gnuplot (open source):          ftp://ftp.gnuplot.vt.edu/pub/gnuplot/

While they are widely used at academic sites, and gnuplot is
standardly included in GNU/Linux distributions, your site
may not have them.  gnuplot can be built and installed like
most GNUware by

        ./configure && make all install

[gnuplot has an extensive demonstration suite, but it must
be run manually; there is no top-level check target to
automate the process.]

configure does not attempt to determine a name for Maple,
because naming conventions for Maple vary from site to site:
the authors' sites have at least these:

        maple           symbolic link to the most recent
                        reliable ASCII version
        mapleV4         ASCII interface to version 4
        mapleV5         ASCII interface to version 5
        mapleV5.1       ASCII interface to version 5.1
        mapleV6.01      ASCII interface to version 6.01

        xmaple          symbolic link to the most recent
                        reliable version
        xmapleV4        X Window System interface to version 4
        xmapleV5        X Window System interface to version 5
        xmapleV5.1      X Window System interface to version 5.1
        xmapleV6.01     X Window System interface to version 6.01

There are generally incompatibilities, and sometimes
significant differences, between these versions.  Our
baseline version during development of this package was
V5.1, although V5 and V6.01 were used on occasion.

Assuming that working versions of maple and gnuplot are
available, and that the variables MAPLE and GNUPLOT in
Makefile point to them, then you can use any of the
plot-relerr-* targets.

Because the base names of the test/*.out files are identical
in double- and quadruple-precision tests, you should only
run plots of one precision at a time.

On completion of a particular test, there will be files
*.out.* in the current directory, with *.out.gnu being
gnuplot input files, and *.out.ps being polished
encapsulated PostScript.  Figures exactly like this were
renamed from .out.ps to .eps and used in the published
article.

Computation of the relative error for plotting needs support
of higher precision than the base one used for the tests.
The file makdat.f can be used to generate data for single-
and double-precision, because it works in
quadruple-precision arithmetic.  However, for best results,
Maple is needed to do the job.

We did not have Maple available on some of our test systems,
so the *.out.* and test/*.out files are copied back to a
system where Maple was available, and the plot-relerr.sh
script was then invoked manually.  "make" cannot be used in
that case, because it would regenerate those files, and it
would supply incorrect compiler names and machine
identification for the graph labels.

plot-relerr.sh includes a critical PostScript optimization
encapsulated in the script fix-gnuplot.sh: without it, the
plots can take up to 30 minutes to print on Lexmark laser
printers.  With the optimization, printing takes only a few
seconds.


======================================
Non-POSIX-conformant operating systems
======================================

Almost all operating systems today offer compliance with one
or more IEEE POSIX standards.  You can find a list of many
of them at

        http://www.math.utah.edu/pub/tex/bib/index-table-i.html#ieeestd

along with pointers to an IEEE catalog of standards.  You
can find a list of certified POSIX systems at

        http://standards.ieee.org/regauth/posix/index.html

which points to further lists at

        http://www.nist.gov/itl/div897/ctg/posix/finalreg4.htm
        http://standards.ieee.org/regauth/posix/posix2.html

Included among these are popular operating systems like
Microsoft Windows, Apple MacOS, and IBM VM/390.

However, just because a system can be made POSIX compliant,
does not imply that every such system is: indeed, you, or
your system manager, will almost certainly have had to
install additional packages to provide this compliance.

There are also multiple sources of UNIX-like environments on
top of Microsoft Windows: see

        http://www.math.utah.edu/~beebe/gnu-on-windows.html

for comments and pointers.

The "configure" scripts and Makefile should work cleanly in
all such environments (at one point during development, test
builds were done in a UNIX-on-Windows environment: the build
was successful, but rather slow).

If you cannot get a POSIX-conformant environment, then you
have to do things by hand:

* adjust constants in the *.inc files (unnecessary if your
  floating-point hardware is IEEE 754-conformant);

* compile the dist/common/*.f files, or at least the subset
  listed in the DLIBSRCS, QLIBSRCS, and SLIBSRCS variables
  in the dist/common/Makefile.in files;

* add the resulting object files to a suitable load library
  and install it in some convenient location for later use.

* copy the dist/*.h files to some place where your C
  compiler can find them easily

You will unfortunately not easily be able to run the
extensive validation suites launched by "make check" in
companion directories, so you will have no means of
validating the accuracy and correctness of the installed
software.  Proceeding-with-fingers-crossed is not a
recommended approach, particularly in view of the large
number of serious errors in vendor Fortran implementations
uncovered by our testing, but sometimes, it is all that you
can do, or have time for.


=====================================
Arithmetic-system-dependent constants
=====================================

See the section with this name in ../common/README.


=======================
Bug and problem reports
=======================

Please send notification of bugs and problems with this
package, and news about ports to any new systems, to the
first author:

        Nelson H. F. Beebe
        Center for Scientific Computing
        University of Utah
        Department of Mathematics, 322 INSCC
        155 S 1400 E RM 233
        Salt Lake City, UT 84112-0090
        USA
        Email: beebe@math.utah.edu, beebe@acm.org, beebe@computer.org,
               beebe@ieee.org (Internet)
        WWW URL: http://www.math.utah.edu/~beebe
        Telephone: +1 801 581 5254
        FAX: +1 801 585 1640, +1 801 581 4148


================
Copyright issues
================

This code is distributed under the usual copyright
arrangement for the ACM Algorithms, as described from time
to time in the journal ACM Transactions on Mathematical
Software.  In general, the copyright provides for
unrestricted use of the software, in both commercial and
noncommercial software.


=====================
Distribution contents
=====================

The distribution file gampsi.tar.gz is a gzipped UNIX tar
archive containing this directory tree:

        dist/common/
        dist/common/save/
        dist/gampsi/
        dist/gampsi/maple/
        dist/gampsi/save/
        dist/gampsi/test/
        dist/gampsi/test/okay/

Thus, unbundling the distribution will produce only a single
file, the subdirectory dist, in the current directory.

Here is a summary of the files:


dist/common/*                   Common code shared by this package, and another
                                by the same authors for Gaussian quadrature
                                with logarithmic weights.  See
                                dist/common/README for a detailed description.

dist/gampsi/Makefile.in         Makefile template used by "configure" to generate
                                Makefile.  NEVER edit Makefile by hand: your
                                changes will be lost the next time "configure" is
                                run.  Instead, override variables on the "make"
                                command line, e.g., "make FOPT=-xO5".

dist/gampsi/aadpsiln.f          Interface to Amos' ACM Algorithm 610
                                code to implement dpsiln().  This was used only
                                for testing of the quality of Amos' dpsifn()
                                function.

dist/gampsi/agen.f              Single-precision data file generator subroutine.

dist/gampsi/agen2.f             Single-precision data file generator
                                subroutine with output suppressed, used for
                                timing tests.

dist/gampsi/configure           GNU autoconf script, run prior to building the
                                software to create the Makefile with suitable
                                settings of variables.  You do NOT need
                                autoconf installed to use the "configure" script!

dist/gampsi/configure.in        GNU autoconf template, used by autoconf to
                                produce "configure" and Makefile.  You should
                                not need to run this, unless you have changed
                                configure.in, in which case, after running it,
                                do "make configure" to create a patched
                                configure file.

dist/gampsi/ctestit.sh          Shell script to run short C and/or C++ test
                                programs.

dist/gampsi/decgam.c            C file to interface Fortran dgamma() to the
                                double-precision function in the C
                                library on Compaq/DEC OSF/1 systems.  This was
                                used only for testing of the quality of the
                                vendor-provided function.

dist/gampsi/decgaml.c           C file to interface Fortran dgamma() to the
                                quadruple-precision function in the C
                                library on Compaq/DEC OSF/1 systems.  This was
                                used only for testing of the quality of the
                                vendor-provided function.

dist/gampsi/delefun.f           Program to test handling of special arguments
                                by Fortran elementary functions.

dist/gampsi/dgen.f              Double-precision data file generator subroutine.

dist/gampsi/dgen2.f             Double-precision data file generator
                                subroutine with output suppressed, used for
                                timing tests.

dist/gampsi/elefun.f            Program to test handling of special arguments
                                by Fortran elementary functions.

dist/gampsi/elefun.sed          sed script used to normalize variations in the
                                representation of Infinity and NaN.

dist/gampsi/fix-gnuplot.sh      Shell script to optimize PostScript from
                                gnuplot.

dist/gampsi/fixexp.sed          sed script to correct D exponents to e
                                exponents; at least one compiler had this bug.

dist/gampsi/funhdr.f            Subroutine to write the comment header in the
                                test/*.out files.

dist/gampsi/gampsi.sok          Spelling exception dictionary for text files in
                                this directory: "spell +gampsi.sok file(s)"
                                runs a spell check.

dist/gampsi/gendat.awk          Program to generate test/*.in data files for
                                double- and quadruple-precision tests.
                                Because the test/*.in files require numbers
                                expressed as integers and powers of two, they
                                are tedious to prepare by hand.  This program,
                                usually run via the gendat.sh script, makes it
                                easy to create the test/*.in files in most
                                cases.

dist/gampsi/gendat.sh           Shell script to run gendat.awk with command-line
                                arguments of xmin xmax functionname.

dist/gampsi/gendats.awk         Analog of gendat.awk, but for single-precision
                                values: the difference is that only 2000,
                                instead of 10000, data points are requested,
                                and instead the range of integer values is
                                reduced to fit in a single-precision
                                significand.  The point count was reduced
                                solely to save disk space in the distribution;
                                no plots of the single-precision errors were
                                used in the paper: 2000 is definitely too few
                                for satisfactory plotting.

dist/gampsi/gendats.sh          Analog of gendat.sh, but for single-precision
                                values.

dist/gampsi/gnugaml.c           C file to interface Fortran dgamma() to the
                                double-precision function in the GNU C library.
                                This was used only for testing of the quality
                                of the vendor-provided function.

dist/gampsi/gslgam.c            C file to interface Fortran dgamma() to the
                                double-precision function in the GNU Scientific
                                Library, gsl.  This was used only for testing
                                of the quality of the vendor-provided function.

dist/gampsi/gslpsi.c            C file to interface Fortran dpsi() to the
                                double-precision function in the GNU Scientific
                                Library, gsl.  This was used only for testing
                                of the quality of the vendor-provided function.

dist/gampsi/hpgam.c             C file to interface Fortran dgamma() to the
                                double-precision function in the C
                                library on HP 9000/7xx HP-UX systems.  This was
                                used only for testing of the quality of the
                                vendor-provided function.

dist/gampsi/ibmgam.c            C file to interface Fortran dgamma() to the
                                double-precision function in the C
                                library on IBM RS/6000 AIX systems.  This was
                                used only for testing of the quality of the
                                vendor-provided function.

dist/gampsi/ibmgaml.c           C file to interface Fortran dgamma() to the
                                quadruple-precision function in the C
                                library on IBM RS/6000 AIX systems.  This was
                                used only for testing of the quality of the
                                vendor-provided function.

dist/gampsi/ibmsgi.pch          Patch file for generating IBM RS/6000 and SGI
                                version of the source code in this directory.
                                See the section ``IBM RS/6000 and SGI systems''
                                above.

dist/gampsi/intomap.awk         Program to convert a test/*.out file to a
                                *.map file that can be processed by Maple to
                                produce a corresponding test/okay/*.out file
                                with high-precision function values.  This
                                program is normally run via the intomap.sh
                                script.

dist/gampsi/intomap.sh          Shell script to convert one or more test/*.out
                                files to *.tmp files, with proposed mv commands
                                to install them in test/okay.  They are not put
                                there automatically, because it is desirable to
                                first check that they have the expected size:
                                bad data in test/*.in files can produce
                                Infinity and NaN in test/*.out files that
                                confuse Maple, which unfortunately lacks a
                                representation for either Infinity or NaN.
                                When a new test file is generated this way, its
                                basename needs to be added to the corresponding
                                CHECKxxx variable in Makefile.in, and then
                                configure needs to be run again to create the
                                Makefile.

dist/gampsi/makdat.f            Program to assist in the reprocessing of
                                test/*.out files to create test/okay/*.out
                                files.

dist/gampsi/maple/Makefile      Makefile used to provide the GNU standard
                                targets in this directory, where no
                                autoconfiguration is needed.

dist/gampsi/maple/chebbas2.map  Maple kernel to produce Chebyshev polynomial
                                fits to psi(x)/(x-x0) and x*Gamma(x) on a unit
                                interval.

dist/gampsi/maple/chebbase.map  Maple kernel to produce Chebyshev polynomial
                                fits to psi(x) and Gamma(x) on a unit interval.

dist/gampsi/maple/chebpol2.map  Maple code to invoke chebbas2.map.  These fits
                                were ultimately not used, but the
                                single-precision fit would be slightly faster
                                than the Pad{\'e} fit that was finally chosen.
                                See the article for details.

dist/gampsi/maple/chebpoly.map  Maple code to invoke chebbase.map.  These fits
                                were ultimately not used, but the
                                single-precision fit would be slightly faster
                                than the Pad{\'e} fit that was finally chosen.
                                See the article for details.

dist/gampsi/maple/gam001.map    Hand-modified output from intomap.sh to
                                generate test/okay/gam001.out with proper
                                handling of Infinity and NaN.

dist/gampsi/maple/gamasymp.map  Maple code to evaluate the term counts needed
                                in the asymptotic series for Gamma(x).

dist/gampsi/maple/gambase.map   Maple kernel to compute Pad{\'e} approximations
                                to Gamma(x) on [1,2].

dist/gampsi/maple/gamloss.map   Maple program to investigate the bit loss in
                                the asymptotic series for Gamma(x).

dist/gampsi/maple/gampade.map   Maple code to invoke gambase.map.

dist/gampsi/maple/lga001.map    Hand-modified output from intomap.sh to
                                generate test/okay/lga001.out with proper
                                handling of Infinity and NaN.

dist/gampsi/maple/mccull.map    Maple program to investigate McCullagh's
                                `rapidly-convergent series' for psi(x).

dist/gampsi/maple/psiasymp.map  Maple code to evaluate the term counts needed
                                in the asymptotic series for psi(x).

dist/gampsi/maple/psibase.map   Maple kernel to compute Pad{\'e} approximations
                                to psi(x) on [1,2].

dist/gampsi/maple/psiloss.map   Maple program to investigate the bit loss in
                                the asymptotic series for psi(x).

dist/gampsi/maple/psipade.map   Maple code to invoke gambase.map.

dist/gampsi/maple/summary.awk   Program to summarize output of the Pad{\'e}
                                approximations fits.

dist/gampsi/maple/xgambase.map  Maple kernel to compute Pad{\'e} approximations
                                to x*Gamma(x) on [1,2].

dist/gampsi/maple/xgampade.map  Maple code to invoke xgambase.map.

dist/gampsi/movefigs.sh         Shell script to save certain files from the
                                *.out.* and test/*.out files created by the
                                plot-relerr-* targets.

dist/gampsi/nagpsiln.f          Interface to NAG library code s14acf()
                                to implement dpsiln().  This was used only for
                                testing of the quality of the vendor-provided
                                function.

dist/gampsi/naggam.f            Interface to NAG library code s14aaf()
                                to implement dgamma().  This was used only for
                                testing of the quality of the vendor-provided
                                function.

dist/gampsi/plot-relerr.sh      Shell script to automate the production of
                                Encapsulated PostScript plots of relative
                                errors; it is invoked by the various
                                plot-relerr-* targets in the Makefile.

dist/gampsi/qelefun.f           Program to test handling of special arguments
                                by Fortran elementary functions.

dist/gampsi/qgen.f              Quadruple-precision data file generator
                                subroutine.

dist/gampsi/qgen2.f             Quadruple-precision data file generator
                                subroutine with output suppressed, used for
                                timing tests.

dist/gampsi/run-par.sh          Shell script to automate builds and tests in
                                parallel.

dist/gampsi/run-tests.sh        Shell script to automate builds and tests for
                                all compilers on one systems.

dist/gampsi/save/Makefile       Backup copy of dist/gampsi/Makefile, for use in
                                the event "configure" fails to complete.

dist/gampsi/save/configure      Backup copy of dist/gampsi/configure, for use in
                                the event "configure" is destroyed by a bad
                                autoconf.

dist/gampsi/sgigam.c            C file to interface Fortran dgamma() to the
                                double-precision function in the C library on
                                SGI IRIX systems.  This was used only for
                                testing of the quality of the vendor-provided
                                function.

dist/gampsi/sgigaml.c           C file to interface Fortran dgamma() to the
                                quadruple-precision function in the C library on
                                SGI IRIX systems.  This was used only for
                                testing of the quality of the vendor-provided
                                function.

dist/gampsi/sungam.c            C file to interface Fortran dgamma() to the
                                double-precision function in the C library on
                                Sun Solaris systems.  This was used only for
                                testing of the quality of the vendor-provided
                                function.

dist/gampsi/sungaml.c           C file to interface Fortran dgamma() to the
                                quadruple-precision function in the C library on
                                Sun Solaris systems.  This was used only for
                                testing of the quality of the vendor-provided
                                function.

dist/gampsi/tafpmx.f            Test program for afpmax().

dist/gampsi/tagen.f             Driver for single-precision data generator
                                agen().

dist/gampsi/tdfpmx.f            Test program for dfpmax().

dist/gampsi/tdgen.f             Driver for double-precision data generator
                                agen().

dist/gampsi/test/*.in           Test input files (see the CHECKxxx variables
                                in Makefile).

dist/gampsi/test/okay/*.out     High-precision output files for use by "make
                                check".

dist/gampsi/testit.sh           Shell script to run short Fortran test programs.

dist/gampsi/tisdinf.f           Test program for isdinf().

dist/gampsi/tisdnan.f           Test program for isdnan().

dist/gampsi/tmdgam.f            Test program for monotonicity checks of
                                dgamma().

dist/gampsi/tmdpsi.f            Test program for monotonicity checks of dpsi().

dist/gampsi/tmgam.f             Test program for monotonicity checks of
                                gamma().

dist/gampsi/tmpsi.f             Test program for monotonicity checks of psi().

dist/gampsi/tmqgam.f            Test program for monotonicity checks of
                                qgamma().

dist/gampsi/tmqpsi.f            Test program for monotonicity checks of qpsi().

dist/gampsi/tqfpmx.f            Test program for qfpmax().

dist/gampsi/tqgen.f             Driver for quadruple-precision data generator
                                agen().

dist/gampsi/tzhang.f            Test program for generating values of Gamma()
                                for comparison with data in the Zhang and Jin
                                book, ``Computation of special functions'',
                                Wiley (1996).


========================================
Manual builds, or, doing it the hard way
========================================

You should try your utmost to get the recommended autoconfigure build
procedure shown above to work: there is great beauty in being able to
build scores of unfamiliar software packages in EXACTLY the same way
on EVERY platform, without EVER having to modify source code files, or
even to look at README files like this!

If you got here, however, perhaps that didn't work, or you have a
crippled computer environment, lacking POSIX support.

Your manual installation task is to get source code files compiled and
installed in a load library to make them easy to use.  On virtually
all UNIX systems, these steps would suffice for a single source file,
foo.f:

        f77 -I../common foo.f
        ar r ../libgjl.a foo.o
        ...
        ranlib ../libgjl.a

The last step (with "ranlib") is needed only once: it creates a symbol
table directory in the library that the linker uses to lookup names to
find which modules (.o files) must be loaded from the library file.
Some UNIX systems lack "ranlib"; they then require "ar rs" (s ==
symbol table) instead of "ar r" in building the library.

On some systems, simply copying a library from one directory to
another can corrupt the linker symbol table, and it may be necessary
to run "ranlib" on the library after it is copied to its final
installation directory.

On IBM PC DOS with one particular compiler, the same job is done by

        f77 /I..\common foo.f
        lib ..\libgjl.lib -+ foo.obj

If your Fortran compiler does not provide for specification of an
include-file path on the command line, or via an environment variable,
then you must copy, or link, the files ../common/*.inc into ../gampsi.

If you have a very old compiler that does not recognize INCLUDE
statements, get a newer one!  They are defined by the ANSI/ISO Fortran
90 and 95 Standards, and have been implemented in most older Fortran
66 and 77 compilers since the 1970s.

Alternatively, since there are no nested INCLUDEs, it should be but a
few minutes' work to write a simple filter in some suitable
programming language to do the insertion. Here is a simple one in awk:

        % cat doincl.awk
        /^ +[Ii][Nn][Cc][Ll][Uu][Dd][Ee] *'/ \
                {
                        gsub(/'/,"",$2)
                        print FILENAME ": " $2 > "/dev/stderr"
                        incfile = ("../common/" $2)
                        while ((getline x < incfile) > 0)
                                print x
                        close incfile
                        next
                }
                { print }

Here is how you would use it:

        % awk -f doincl.awk foo.f >tmp/foo.f

Public-domain and commercial awk implementations are available for
most operating systems, and awk is part of the POSIX standard.

You have to repeat the compilation and library-update steps for the
following files to get each compiled and added to the load library.
On some systems, this may be easier if you combine them into a
temporary file first, such as this IBM PC DOS example:

        copy dfpmax.f+diran.f+dlgam.f+dpsiln.f+dran.f+ffalse.f+ftrue.f+idceil.f+isdinf.f foo.f
        f77 /I..\common foo.f
        lib ..\libgjl.lib -+ foo.obj

Here are the files that need to be compiled and installed in the
library:

        ../common: (single-precision code)
                aeps.f
                afpmax.f
                ainf.f
                airan.f
                algam.f
                alog2.f
                anan.f
                astore.f
                astorf.f
                gamma.f
                iceil.f
                isainf.f
                isanan.f
                psi.f
                psiln.f
                ran.f

        ../common: (double-precision code)
                dcopy.f
                deps.f
                derbit.f
                dfloat.f
                dfpmax.f
                dgamma.f
                dinf.f
                diran.f
                dlgam.f
                dlog2.f
                dnan.f
                dpsi.f
                dpsiln.f
                dpsum.f
                dran.f
                dstore.f
                dstorf.f
                ffalse.f
                ftrue.f
                idceil.f
                isdinf.f
                isdnan.f
                prthdr.f
                pythag.f
                tql1.f
                trapit.f

        ../common: (quadruple-precision code)
                iqceil.f
                isqinf.f
                isqnan.f
                qeps.f
                qepsln.f
                qfloat.f
                qfpmax.f
                qgamma.f
                qinf.f
                qiran.f
                qlgam.f
                qlog2.f
                qnan.f
                qpsi.f
                qpsiln.f
                qstore.f
                qstorf.f

Once the library is built, you can link your own code against it, or
you can run members of the test suite.

The test programs are:

        ../gampsi:
                tafpmx.f
                tagen.f
                tdfpmx.f
                tdgen.f
                tisdinf.f
                tisdnan.f
                tlgam.f
                tmdgam.f
                tmdpsi.f
                tmgam.f
                tmpsi.f
                tmqgam.f
                tmqpsi.f
                tqfpmx.f
                tqgen.f
                tzhang.f

On UNIX, here is how you might build one of them, and run one test,
assuming a Bourne-shell compatible shell:

        cd ../gampsi
        f77 -o tdgen tdgen.f funhdr.f dgen2.f -L../lib -lgjl
        cd test
        ../tdgen < gam001.in > gam001.out 2> gam001.err
        ndiff --relerr 5.0e-11 --minwidth 10 okay/gam001.out gam001.out
        ndiff --relerr 5.0e-11 --minwidth 10 okay/gam001.err gam001.err

You can find all of the test files listed in the

        CHECKxyz = ...

lines in the Makefile (or Makefile.in) in each directory.

There are a large number of test input files, each with extension .in,
in the test subdirectories:

../gampsi/test:         114

Clearly, running these tests by hand is a very large task.  That is
why we wrote down rules in the Makefile.in files, which, after running
./configure, become Makefile files that "make" can use to do the
entire job automatically.

-------------------------------------The End------------------------------------
