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 transp_support@pppl.gov --repackaging of code from netlib (http://www.netlib.org) --original code by slatec authors-- see netlib. o CONTACT transp_support@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 .//, 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 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- /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 /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/lib -lr8slatec Make sure users know what 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: transp_support, Princeton University transp_support@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 -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".