README for the NTCC R8slatec Module

The module is available through the NTCC Webpage,
w3.pppl.gov/NTTC  under "Modules Library", as compressed
tarfile, r8slatec.tar.gz, and as zip archive, r8slatec.zip.
Alternatively it can be obtained from ftp.pppl.gov
in pub/NTCC/.


o AUTHOR
  D. McCune dmccune@pppl.gov 
  --repackaging of code from netlib (http://www.netlib.org)
  --original code by slatec authors-- see netlib.

o CONTACT
  ntcc_webmaster@pppl.gov  
  D. McCune          : dmccune@pppl.gov 
  C. Ludescher-Furth : cludesche@pppl.gov

****************
REVISION HISTORY
****************
      date         Description

  Jun 30, 1999  -- Created
  Mar 24, 2003  -- added "dpolft", to replace NAG "e02adf"
----------------------------------------------------------------

Index:
   1. CONTENTS
   2. UNPACKING INSTRUCTIONS
   3. DESTINATIONS
   4. BUILDING INSTRUCTIONS
   5. RUNNING INSTRUCTIONS
   6. TESTING INSTRUCTIONS
   7. FINAL INSTALLATION
   8. APPENDIX
      -Abstract
      -FAQ

************
1. CONTENTS:
************


README_Slatec:   This file.  Brief descriptions of the other files,
                 and instructions for compiling r8slatec and its
                 test program.

Makefile:        NOTE, "GNU make" must be used
                 (usually in /usr/gnu/bin or /usr/local/bin).
		 Main Makefile to envoke Makefile(s) in subdirectories.  

./share/Make.flags:  Include file for Makefile, to setup Flags, etc.

-- in subdirectory r8slatec:
   README		-   copy of README_Slatec:
   Notes_dpolft		-   Notes on dpolft_test
   slatec_r8.table      -   R4 -> R8 conversion table
   r8slates.sample_output - Reference output from r8slates.
   dpolft_test.ind	-   Input Sample for dpolft_test program.
   dpolft_test.ps	-   Outut from "dpolft_test @dpolft_test" 
			    in PS format.
   dpolft_test.reference_output - Outut from "dpolft_test @dpolft_test"
			          in text format.
   Sources to build library libr8slatec.a and test programs,
   dpolft_test and r8slates.
   
-- in subdirectory portlib:
   Sources to build internally used library libportlib.a:
   *.F. *.f9f, *.c, *.h

-- in subdirectory fpreproc:
   Python scripts for fortran pre-processing.

For dpolft_test:
-- in subdirectories comput, ureadsub, trgraf, vaxonly and generic_dummy:
   Makefile
   Sources to build libraries needed by dpolft_test.


**************************
2. UNPACKING INSTRUCTIONS:
**************************

for tarfiles:
  > gunzip r8slatec.tar.gz
  > tar xvf r8slatec.tar

or, for zip archives:
  > unzip r8slatec.zip


****************
3. DESTINATIONS:
****************
Or where do the files go?

When you extract the tar file you get sub directories:
./r8slatec  --  sources and Makefile
./share             --  include file Make.flags, Make.local.sample
./portlib           --  internally used library
./include/fpreproc  --  *.h files for cpp
./fpreproc          --  scripts for pre-processing of fortran

For dpolft_test only:
./comput            --  transformation/interpolation routines
./sglib             --  Scientific Graphics Library.
./ureadsub          --  Terminal control/interactive program automation.
./trgraf            --  Interactive Data Display Library.
./vaxonly           --  miscellaneous

The location of the following subtrees, containing binaries, can be
controlled via environment variable "OBJ".
   
test         : for test programs and the sample data
lib          : for the libraries
mod:     for fortran 90 modules
obj/*        : for compiled objects and pre-processed sources


By default obove directories are created in ./<MACHINE>/, where
MACHINE is defined in Make.flags.
e.g.: if you are running Linux, the destination would be ./LINUX/obj, etc.

You can overwrite the destination by defining OBJ, as an environment
variable (e.g. export OBJ=/dir1/dir2),
or with make (e.g. "make all OBJ=.").
If OBJ is defined, the destinations will be
$OBJ/lib and $OBJ/test.
If OBJ is defined as "." then, in the example above, the destination
would be $HOME/foo/lib.

The rational behind <MACHINE> is to facilitate building for various platforms.

Note: If you define OBJ as option to gmake, you have to consistently do so;
      e.g: gmake clean OBJ=., gmake install OBJ=.

*************************
4. BUILDING INSTRUCTIONS:
************************* 

For dpolft_test ONLY:
      Required Libraries:
           netCDF         -  network Common Data Form
               If netCDF is in a non-standard location,
               you can define it via NETCDF_DIR.
      Optional Libraries:
           NAG Library - for comparison
               If you have the NAG library, define NAGLIB.
               e.g.: NAGLIB=/usr/local/lff95/lib/libnag.a

	   readline, history, termcap  for Command Line Editing
           Note: if not all three libraries are installed
                 you must define NO_EDITLIBS
		 e.g.: gmake NO_EDITLIBS=Y


> gmake            -- to build/link library, r8slates and dpolft_test
                      using dummy naglib for dpolft_test

> gmake NAGLIB=/usr/local/lib/libnag.a
                   -- using libnag for dpolft_test


> gmake checklibs  -- tells you what the makefile will do
                      (without any action);
                      it says which libraries it will make and
                      which ones it already found and where.

> gmake show_makeflags -- to see what flags, definitions Make will use

To use debugger:
> gmake DEBUG=y

> gmake clean      -- to remove all .o files
> gmake realclean  -- to remove everything but sources.



Compiling on Linux:
-------------------
By default the Makefile will select LaheyFujitsu.

To select a different compiler define
FORTRAN_VARIANT to "Portland"  "NagWare"  "Fujitsu" "Intel" or "Absoft"

e.g.:
setenv FORTRAN_VARIANT Portland (csh)
FORTRAN_VARIANT=Portland; export  FORTRAN_VARIANT (sh)

Alternatively, FORTRAN_VARIANT can be passed directly to the gmake
command, as in:
gmake  FORTRAN_VARIANT=Portland

To use NAG95: 
> gmake FC=f95 FC90=f95

To use NAG90: 
> gmake NAG90=y

To use vastf90:
> gmake VAST90=y

Caveat: Be careful to use the same compiler for all objects.

Compiling on Alpha Linux:
-------------------------
The Makefile assumes the Compaq compiler and specifies the 
 " -assume no2underscores " option.

Therefore the calling user software must also be compiled with this
option, or you should edit share/Make.flags to remove the option.


Compiling on SUN:
-----------------
The Makefile specifies the -dalign option.
Therefore the calling user software must also be compiled with this
option, or you should edit share/Make.flags to remove the option.

************************
5. TESTING INSTRUCTIONS:
************************

directory $OBJ/test  -or-  <MACHINE>/test  will contain the following
files:
dpolft_test            : shows comparison dpolft to e02adf.
dpolft_test.ind        : input script for dpolft_test
porttest               : test for portlib
r8slates               : test driver
r8slates.sample_output : sample output from  r8slates

To run tests:
=============
For dpolft_test, define environment variable TERMINAL_TYPE = XTERM
                 (e.g. export TERMINAL_TYPE=XTERM)
		 See Notes_dpolft (in subdirectory r8slatec)

cd <MACHINE>/test  or  cd $OBJ/test

./r8slates -- based on the TEST03 driver available from SLATEC on netlib.
              This code contains its own reference data and will report
              any errors explicitly.  An example of what its output should
              look like is shown in r8slates.sample_output

./dpolft_test @dpolft_test
	      this puts the program through its paces, showing the very close
              equivalence of dpolft to e02adf for a series of analytic test
              functions.


**********************
7. FINAL INSTALLATION:
**********************

Choose or create the root directory in which you wish to install the software.
A common location would be /usr/ntcc, but installation can occur in any 
directory where you have appropriate permissions.

You define your choice of root directory via PREFIX.

The assumptions are:

library in:          $PREFIX/lib        = $LIBDIR       
slatec_r8.table in:  $PREFIX/etc/ftoken = $ETCDIR/ftoken       
man page in:         $PREFIX/man/man3   = $MANDIR/man3

To install the software, return to the top directory (the directory,
where you downloaded the tar files) and type

> gmake install  
    to install into /usr/ntcc/...

> gmake install PREFIX=/dir1/dir2/
    to install into /dir1/dir2/...

If you want things elsewhere, you can overwrite the default with
> gmake install LIBDIR=/xxx ETCDIR=yyy MANDIR=/zzz

NOTE:
-----
The library is installed as libr8slatec.a
Users should link with

-L<PREFIX>/lib -lr8slatec

Make sure users know what <PREFIX> is.

After you have installed the software, you can delete the entire tree
with
> cd ..
> rm -r foo
   assuming the previous example.

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

IF YOU HAVE ANY PROBLEMS, PLEASE CONTACT EITHER:


        Doug McCune, Princeton University
                dmccune@pppl.gov
        or

        Christiane Ludescher-Furth, Princeton University
                cludescher@pppl.gov
        or      
                ntcc_webmaster@pppl.gov


=====================================================================

*********
APPENDIX:
*********


o Abstract: 

This is a repackaging of a subset of the "SLATEC"
library of mathematical functions.  The complete library is
available from netlib (http://www.netlib.org/slatec/index.html).
The subset provided in this module consists of only the double
precision routines from SLATEC category C:  elementary and
special functions (see http://www.netlib.org/slatec/toc).
Examples of contents are:  error function, gamma function,
Bessel functions, etc.



o Frequently Asked Questions:

  Q:  Has the SLATEC source been modified?
  A:  No.  These are the version 4.1 SLATEC routines exactly as
      provided by netlib.

  Q:  Why take only the double precision routines?
  A:  Many of the function evaluations in SLATEC are carried out
      by truncated Taylor series expansions.  The number of terms
      retained in these expansions dictate that the single precision
      routines are really only accurate for 32 bit floating point
      arithmetic.  The double precision routines are good for 64 bits.
      On Cray systems, R8slatec is compiled to map double precision to
      Cray single precision.  Thus the library can be used in a REAL*8
      code with portability between Cray and conventional 32 bit 
      workstation environments.  A goal of the NTCC Modules Library
      is to encourage portable fortran programming practices.  There
      is no hope for the portability of single precision codes, hence
      the choice to include only the double precision (really, 64 bit)
      SLATEC routines.

  Q:  Why take only the C category subset of SLATEC?
  A:  SLATEC includes a version of BLAS and other routines which are
      better distributed by other means.  In the case of BLAS in
      particular, users should seek system provided routines that are
      optimized to the local machine architecture.

  Q:  I have a code which makes single precision SLATEC calls.  How
      can I make use of this library?
  A:  This would only be practical in the context of converting your
      code to REAL*8 precision.  The NTCC Modules Library includes a set
      of "portability tools" to facilitate this conversion.  One of 
      the tools, inside the "ftoken" module, is a tool called "fgtok".
      The R8slatec modules contains a file "slatec_r8.table" which 
      contains the mapping of SLATEC names from single to double
      precision, in a format understood by fgtok.  So,

         fgtok  <old-source-code> <new-source-code> -s slatec_r8.table

      will convert all single precision SLATEC special function calls.
      The conversion of fortran code to REAL*8 precision is highly 
      desirable, because the result is code which runs identically on
      Cray and on workstation environments.
     
  Q:  where can I find documentation for these routines.
  A:  the source code comments give very precise definitions of the
      interfaces of individual routines.  For more general information
      point your browser at "http://www.netlib.org/slatec/index.html".
