                      Software Distribution for

   Algorithm xxx: GAUSSLOG --- A Package of Routines for Generating
 Gaussian Quadrature for Two Classes of Logarithmic Weight Functions
              and the Associated Orthogonal Polynomials

                                  by

                          Nelson H. F. Beebe
                                 and
                            James S. Ball

                          University of Utah
                            [14-Dec-2000]
		    [08-Nov-2003] [minor updates]


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

        Quick and (usually) clean installation
        Quick demo
        Introduction
        Building, validation, and installation
        IBM RS/6000 and SGI systems
        Portland Group, Inc. Fortran compilers
        Non-IEEE 754 systems
        Non-POSIX-conformant operating systems
        Arithmetic-system-dependent constants
        Bug and problem reports
        Copyright issues
        Include file dependencies
        Manual builds, or, doing it the hard way


======================================
Quick and (usually) clean installation
======================================

At many sites, these simple commands

        ./configure && make all check install

will build, validate, and install these packages.  Unless this fails,
or you want to control choice of compilers, compilation options, and
installation directories, you can stop reading this file now :^).

If your system supports quadruple-precision arithmetic in Fortran, you
can do

	make all-qp
	make check-qp

The quadruple-precision version of the package is independent of the
double-precision version, but since all routine names are distinct in
the two cases, they are collected into a common load library.

If you are in doubt about what the output should be, the test/okay
subdirectories contains *.err, *.out, and *.dat files from the
author's development site which are believed to be correct.  They were
produced on Sun Solaris 7, 8, and 9 using the Sun native C, Fortran
77, and Fortran 90 compilers in the Workshop 6, Workshop 7, and Studio
8 compiler releases.

The validation tests normally delete output files that are deemed to
be acceptably close to the correct ones.  Should you wish to preserve
them for closer examination, simply redefine the rm command for the
duration of the testing, like this:

	make check RM='echo Keeping'


==========
Quick demo
==========

After successfully building the packages with

	./configure && make all

you can run a quick demonstration of their use with

	make demo		# double-precision code

If your system supports it, you can also run

	make demo-qp		# quadruple-precision code

The output produces data reported in tables in the TOMS article, as
well as data tabulated in Abramowitz and Stegun's well-known NBS
Handbook of Mathematical Functions.  The NBS comparison, however,
tests only the quadrature for the nonlogarithmic integrals.


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

This README file is provided in a subdirectory (either jacobi or
laguerre: the two copies of this file are identical) of a directory
tree for the ACM Transactions on Mathematics Software Algorithm in the
title above.  The software subdirectories are

        ../common
        ../jacobi
        ../laguerre

and the UNIX manual page subdirectory is

        man

The ../common directory is also shared by another ACM TOMS Algorithm,

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

by the same authors; there is a corresponding directory, ../gampsi,
for it.  The two packages are, however, INDEPENDENT.

For portability, ALL file names in this directory tree conform to the
draconian IBM PC-DOS 8+3 limit, and the old UNIX System III and V
14-character limit, which can be checked like this:

        find . -type f | sort | doschk

The doschk utility is available at

        ftp://ftp.gnu.org/pub/gnu/non-gnu/doschk/doschk-1.1.tar.gz

File names are generally spelled entirely in lowercase, with a few
exceptions:

        INSTALL
        MKDIRS
        Makefile
        Makefile.in
        README

Their initial uppercase letters place them at the beginning of a
directory contents listing (by, e.g., the UNIX "ls" command) for
better visibility, and conformance to widespread conventions.
However, no harm, or collisions, will arise from all file names being
mapped to a single lettercase.

As its name implies, subdirectory ../common contains code shared by
software in the other three software directories.

The ../jacobi and ../laguerre directories belong to package GAUSSLOG.

This software tree uses the Free Software Foundation's GNU Project
autoconfigure system to significantly facilitate the compilation,
linking, testing, and installation of complex software packages.

The autoconfigure software should be usable on ANY POSIX-conformant
system, which includes all stock UNIX variants, including GNU/Linux,
and also on most other operating systems, PROVIDED that the additional
POSIX support has been installed on them.

More information on POSIX issues can be found in ../common/README.

The autoconfigure system is now described in a book:

        @String{pub-NRP                 = "New Riders Publishing"}

        @String{pub-NRP:adr             = "Carmel, IN, USA"}

        @Book{Vaughan:2000:GAA,
          author =       "Gary V. Vaughan and Ben Elliston and Tom Tromey and
                         Ian Lance Taylor",
          title =        "{GNU} Autoconf, Automake and Libtool",
          publisher =    pub-NRP,
          address =      pub-NRP:adr,
          pages =        "xx + 390",
          year =         "2000",
          ISBN =         "1-57870-190-2",
          LCCN =         "QA76.76.O63 G598 2000",
          bibdate =      "Sat Feb 24 11:27:09 2001",
          price =        "US\$40.00",
	  URL =          "http://www.newriders.com/books/title.cfm?isbn=1578701902;
			 http://sources.redhat.com/autobook/;
			 http://sources.redhat.com/autobook/autobook/autobook_toc.html;
			 http://sources.redhat.com/autobook/download.html",
          acknowledgement = ack-nhfb,
        }

Nevertheless, installation of an autoconfigured package does NOT require
prior installation of the GNU autoconf package: that is only needed if
you wish to modify the short configure.in files, and then regenerate
the big configure scripts, which are 6 to 130 times bigger in the
subdirectories here.  Should you wish to do so (for example, for a
port to a new system where the standard configure scripts fail), you
can find autoconf at

        ftp://ftp.gnu.org/gnu/autoconf/autoconf-2.13.tar.gz

Make sure to get the latest version if you do this; 2.13 has been
stable since 15-Jan-1999.  The authors shall, of course, be pleased to
receive any resulting updates to the configure.in and Makefile.in
files; the shortest, and best, way to communicate such updates is to
send NHFB the output of "diff -c" between the original and changed
files.


======================================
Building, validation, and installation
======================================

To build, validate, and install the part of the package in this
directory:

        ./configure && make all check install

The first of these can be omitted if you have already done it.

To specify compilers, set environment variables for CC (C or C++
compiler name, optionally with special flags (e.g., CC='c89 -posix')),
and F77 (Fortran 77, 90, 95 or HPF compiler name, optionally with
special flags (e.g., F77='f77 -fpe3')):

        env CC=CC F77=f90 ./configure && make all check install

The "env" command works in all known UNIX shells, eliminating the
nuisance of syntax variations in the setting of environment variables
in different shells.

NB: The test programs intentionally generate at least one overflow, in
subroutine getnan() (../common/getnan.f): on machines with IEEE 754
arithmetic, this should be transparent.  Unfortunately, some compilers
do not by default provide the full IEEE 754 environment, and terminate
on overflow or zero divide.  Also, some Fortran 90 and 95 compilers
need notification of fixed source format.

Here are additional Fortran compiler switches that may be needed at
your site:

    ---------------------------------------------------------------------
    Compiler(s)     Operating System                     Options
    ---------------------------------------------------------------------
    nagf90, nagf95  all UNIX                      -ieee=full -w=obs
    f90, f95        Sun Solaris 2.x               -ftrap=%none
    xlf90, xlf95    IBM RS/6000 AIX 4.x           -qfixed
    f77, f90, f95   Compaq/DEC OSF/1 4.x (Tru64)  -fpe2 or -fpe3 or -fpe4
    ---------------------------------------------------------------------

You can set them at in configure time in the variable FFLAGS:

	env CC=CC F77=f77 FFLAGS=-fpe3 ./configure && make all check install

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...

Unless overridden by the F77 environment variable, ./configure will
search for the first Fortran compiler 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.

If you are a system manager, and the GNU-standard /usr/local is an
acceptable location, that single command line at the start of this
section should suffice.

Otherwise, if you use non-standard installation trees, or are a user
without privileges to write into a shared system-wide directory tree,
you can change the installation location like this:

        ./configure --prefix=/some/other/path && make all check install

or

        ./configure && make all check install prefix=/some/other/path

For a single unprivileged user, $HOME/local is a recommended choice for
/some/other/path.

Under NO CIRCUMSTANCES should you ever do local software installations
with the prefix set to /usr; doing so will make it impossible to
distinguish locally-installed software from vendor software, and all
of your locally-added material will be lost when you next upgrade your
operating system!

At most large POSIX sites, /usr/local is a file tree shared among
machines of compatible architectures; thus, in a multi-platform
environment, you will need to repeat the installation only once per
architecture, rather than once per individual machine.

Assuming that $PREFIX stands for the value of the --prefix option, or
the Makefile "prefix" variable when "make install" is run, the
installation will place files in these standard directories, which
must already exist:

        $PREFIX/lib
        $PREFIX/man/man3

In addition, files will be installed here too,

        $PREFIX/man/html/man3
        $PREFIX/man/pdf/man3
        $PREFIX/man/ps/man3

but ONLY if these directories already exist.

To encourage software installations to be put in standard places, some
software package authors, including at least one of us, consider it
bad form for a package installation to create new installation
directories, unless they are intended to be used solely for that
package, so "make install" for this package will NOT create any new
directories.

For convenience, a command like

        ./MKDIRS --prefix=/some/other/path

tries to create the required installation directory tree, assuming
/some/other/path is changed to something sensible :^)!

Although UNIX manual pages for library routines conventionally go into
a directory tree .../man/man3 (raw nroff/troff files) and .../man/cat3
(formatted ASCII text files), no widely-adopted convention exists
for where HTML, PostScript, and PDF forms of the formatted manual
pages should be installed.  The settings above reflect reasonable
choices made at the authors' sites.

The default UNIX manual page installation locations can always be
overridden at install time, like this:

        cd man; make install \
                        htmldir=/some/directory \
                        mandir=/some/other/directory \
                        pdfdir=/yet/another/directory \
                        psdir=/yet/one/more/directory


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

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


======================================
Portland Group, Inc. Fortran compilers
======================================

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


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

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


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

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


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

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


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

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


================
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.


=========================
Include file dependencies
=========================

Source code files in directory ../jacobi depend on these INCLUDE
files, stored in ../common:

        dlgtwo.inc
        ecodes.inc
        maxpts.inc
        qlgtwo.inc
        stdio.inc

Source code files in directory ../laguerre depend on these INCLUDE
files, stored in ../common:

        ecodes.inc
        maxpts.inc
        stdio.inc

No system- or architecture-dependent changes are expected to be
required in any of these, unless your Fortran implementation has
uncommon choices of the unit numbers set in stdio.inc (normally,
stderr == 0, stdin == 5, stdout == 6).


========================================
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 ../jacobi
and ../laguerre.

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 gjqf.f+gjqfd.f+gjqli.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) [not used by GAUSSLOG package]:
                aeps.f
                afpmax.f
                ainf.f
                airan.f
                algam.f
                alog2.f
                anan.f
                astore.f
                astorf.f
		avsum.f
                gamma.f
                iceil.f
                isainf.f
                isanan.f
                psi.f
                psiln.f
                ran.f

        ../common: (double-precision code) [not used by GAUSSLOG package]:
                dfpmax.f
                diran.f
                dlgam.f
                dpsiln.f
                dran.f
                ffalse.f
                ftrue.f
                idceil.f
                isdinf.f

        ../common: (double-precision code):
                dcopy.f
                deps.f
                derbit.f
                dfloat.f
                dgamma.f
                dinf.f
                dlog2.f
                dnan.f
                dpsi.f
                dstore.f
                dstorf.f
		dvsum.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
		qvsum.f

        ../jacobi:
                gjqf.f
                gjqfd.f
                gjqli.f
                gjqrc.f

        ../laguerre:
                glqf.f
                glqfd.f
                glqli.f
                glqrc.f

        ../jacobi: (quadruple-precision code)
                qgjqf.f
                qgjqfd.f
                qgjqli.f
                qgjqrc.f

        ../laguerre: (quadruple-precision code)
                qglqf.f
                qglqfd.f
                qglqli.f
                qglqrc.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:

        ../jacobi:
                tgjf1.f
                tgjf2.f
                tgjfd1.f
                tgjfd2.f

        ../laguerre:
                tglf1.f
                tglf2.f
                tglf3.f
                tglf4.f
                tglf5.f
                tglf6.f
                tglfd1.f
                tglfd2.f
                tglfd3.f
                tglfd4.f
                tglfd5.f
                tglfd6.f

        ../jacobi: (quadruple-precision code)
                tqgjf1.f
                tqgjf2.f
                tqgjfd1.f
                tqgjfd2.f

        ../laguerre: (quadruple-precision code)
                tqglf1.f
                tqglf2.f
                tqglf3.f
                tqglf4.f
                tqglf5.f
                tqglf6.f
                tqglfd1.f
                tqglfd2.f
                tqglfd3.f
                tqglfd4.f
                tqglfd5.f
                tqglfd6.f

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

        cd ../jacobi
        f77 -o tqjf1 tqjf1.f -L../lib -lgjl
        cd test
        ../tqjf1 < gjf101.in > gjf101.out 2> gjf101.err
        ndiff --relerr 5.0e-11 --minwidth 10 okay/gjf101.out gjf101.out
        ndiff --relerr 5.0e-11 --minwidth 10 okay/gjf101.err gjf101.err

You can find all of the test files listed in the

        CHECKGxyz = ...

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     [not used by GAUSSLOG package]
../jacobi/test:          40
../laguerre/test:       177

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--------------------------------
