README_Pspline

README file for Pspline Module

Prepared by C.Ludescher-Furth -- ludescher@pppl.gov 10/23/00

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

  May 15, 1999  -- Created 
  Apr 12, 2000  -- Houlberg/Pletzer enhancements

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

SINGLE/DOUBLE PRECISION VERSION

Standard Single Precision and REAL*8 versions are distributed
in pspline.{tar.gz,zip}".
NOTE, REAL*8 soubroutines are prefixed with "r8".


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


************
1. CONTENTS:
************
This directory should contain the following files:

README_Pspline:  This file.  Brief descriptions of the other files, and
                 instructions for compiling, testing and installing the
                 pspline library libpspline.a and its test drivers
                 pspltes{t,8}, qk_pspline, ezspline_* and czspline_test.cxx. 

EzSpline_HowTo:  FAQ for EzSpline.
EzSpline_README: User Guide for EzSpline 
CzSpline_README: User Guide for CzSpline 

Makefile:       NOTE, "GNU make" must be used
                      (usually in /usr/gnu/bin or /usr/local/bin).
                      You also need "gcc" for pre-processing
                      (exept on CRAY).
		Main Makefile to invoke Makefiles in all subdirectories.  

./ezcdf
   Makefile               -- to build libezcdf.a
   Sources to build libezcdf.a, an internally used library
   
./include/fpreproc:
   *.h files for source pre-processing.

./pspline:
   README       -- A copy of README_Pspline from above.
   Makefile     -- to build libpspline and test programs
   Sources to build the library libpspline.a
           NOTE, REAL*8 sources are prefixed with "r8".
   pspltes{t,8}.for       -- source for basic test driver
   pspltes{t,8}.output    -- sample output file for respective test case
   {r8}lookup_test   	  -- source to study performance
   {r8}lookup_test.output -- sample output file for respective test case
   ezspline_test_{r4,r8}  -- source to test ezspline
   ezspline_perf_{r4,r8}  -- source to test ezspline
   ezspline_test_*.ref    -- sample output file for respective test case
   ezspline_test.m        -- matlab program to display the test output 
   qk_pspline.f90         -- source for derivative test driver
   qk_pspline.output    -- sample output file for respective test case

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

**************************
2. UNPACKING INSTRUCTIONS:
**************************
for tarfiles:
  > gunzip pspline.tar.gz
  > tar xvf pspline.tar

or, for zip archives:
  > unzip pspline.zip


****************
3. DESTINATIONS:
****************
Or where do the files go?
(this refers to building and testing; see FINAL INSTALLATION for end result) 


When you extract the tar file you get sub directories:
./pspline          --  Spline and Hermite Cubic Interpolation 
./ezcdf            --  Easy Interface for netCDF Routines
./share            --  include file Make.flags 
./portlib          --  portability routines
./include/fpreproc --  *.h files for cpp

The makefile will create more sub directories,
lib:           for the library, libpspline.a
mod:           for the f90 modules
obj/<libname>: for compiled objects
test:          for the test programs and the sample output files.

By default these directories are created in  
./<MACHINE>, which is determined by Make.flags.
e.g.: if you are running Linux, and the tar file resides in $HOME/foo,
      the directories would be in
      $HOME/foo/LINUX/{lib,mod,obj,test}.

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

The rationale 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=.
      Alternatively you can modify share/Make.local.sample
      and rename it to share/Make.local.

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

Required Compilers:
===================
   gcc        -- for pre-processing (exept on CRAY)
   Fortran 90
   C

Required Libraries:
===================
   netCDF
         The library is assumed to be in /usr/local/{lib,include}
         If your site has it somwhere else, define NETCDF_DIR
         e.g. gmake NETCDF_DIR=/my/nonstandard
         (on CRAY, the Makefile knows where it is)
         Alternatively you can modify share/Make.local.sample
         and rename it to share/Make.local.

>>>>Note: If you don't have netCDF installed, do this:
         > cp cdf_dummy/netcdf.inc include/
         > gmake NETCDF_DIR=   


> gmake            -- to compile library and link all test programs

> 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.
                      It also tells you how to rebuild an existing library.
 
> gmake clean      -- to remove objects
> gmake realclean  -- to remove objects and library

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


COMPILING FLAGS:
----------------
By default all routines are compiled with the automatic flag.
If you want static, say:

> gmake DYNAMIC=

On IRIX64:
> gmake DYNAMIC=-static

On CRAY:
> gmake DYNAMIC=-ev

On HP
> gmake DYNAMIC=-K


Compiling on Linux:
-------------------

By default the Makefile will select Lahey Fujitsu f95.

To select a different compiler define
FORTRAN_VARIANT to "Portland" "PathScale" " GCC" "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

Note: some test programs are linked with g++; to find the Fortran libraries,
      you need to define FLIBROOT
      e.g. export FLIBROOT=/usr/pppl/lf64x/lf6480

To use vastf90:
> gmake VAST90=y

To use NAG90: 
> gmake NAG90=y


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 " -fast " option which includes -dalign.
Therefore the calling user software must also be compiled with this
option, or you should edit share/Make.flags to remove the option.


************************
5. RUNNING INSTRUCTIONS:
************************
Be sure your "stack size" is adequate ~ 32000 (100000 on alpha), otherwise
you might get segmentation faults.
To check yor stack size:
> ulimit -a
To increase it:
> ulimit -Ss 131072

************************
6. TESTING INSTRUCTIONS:
************************

To verify functioning of the software:
--------------------------------------

There is no input required.
Run pspltes{t,8} and compare it's output
with  pspltes{t,8}.output:

e.g.:
> cd <MACHINE>/test        or   > cd $OBJ/test 
> ./pspltes{t,8} > foo
> diff foo pspltes{t,8}.output

To study performance of pspline software:
-----------------------------------------
e.g.:
> ./{r8}lookup_test > {r8}foo
> diff {r8}foo {r8}lookup_test.output

To test derivatives:
---------------------
e.g.:
> ./qk_pspline > qk_foo
> diff qk_foo qk_pspline.output

To test ezspline:
-----------------
e.g.:
> ./ezspline_test_{r4,r8}
  then look at it with matlab:
> matlab
  >> ezspline_test

To test c interface:
-----------------
e.g.:
> ./czspline_test

************************
7. DOCUMENTATION:
************************

PSPLINE Home Page:
http://w3.pppl.gov/NTCC/PSPLINE

PSPLINE HELP
http://w3.pppl.gov/~pshare/help/pspline.htm

NTCC Home Page:
http://w3.pppl.gov/NTCC


**********************
8. 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 default for PREFIX is /usr/ntcc.

The assumptions are:

libraries in:       $PREFIX/lib        = $LIBDIR
f90 modules in:     $PREFIX/mod        = $MODDIR
man pages 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 PREFIX=/dir1/dir2/
    to install into /dir1/dir2/...

>   gmake install  
    to install into /usr/ntcc/...
    or, if PREFIX is defined in share/Make.local

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

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

-L<PREFIX>/lib -lpspline

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