README for NTCC LSODE Module.

The module is available through the NTCC Webpage,
w3.pppl.gov/NTTC  under "Modules Library", as compressed
tarfile, lsode.tar.gz, and as zip archive, lsode.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 lsode authors-- see netlib.

o CONTACT
  ntcc_webmaster@pppl.gov  
  D. McCune : dmccune@pppl.gov 

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

  July 22, 1999  -- Created

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

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


************
1. SYNOPSIS:    
************

The NTCC copy of LSODE was mechanically created from netlib (odepack)
lsode using REAL*8 conversion tools.
The test program, lsode_test, is extracted from the odepack demo test
driver, and was demonstrated on a DEC alpha workstation to generate the
same results as when using the unconverted double precision lsode.

The result is a REAL*8 precision lsode routine-- it is a single source
which can be used for either cray single precision (64 bit) or workstation 
double precision (64 bit) arithmetic.

Handling of lsode dependencies:

Cpp-style preprocessing at compile time is used to switch between single 
precision and double precision versions of the linpack routines (and
r1mach and d1mach) upon which lsode depends.  (The compile time
preprocessing is as per NTCC portability module "fpreproc").

A library lsode_linpack is provided which contains only the linpack
routines upon which lsode depends (both single and double precision
versions).  The user can use this library, if a complete linpack is not 
locally available.  The sources in this library were downloaded from 
netlib (http://www.netlib.org) with no modification.

The r1mach and d1mach references can be resolved using the NTCC portlib
library (cf NTCC portability module "portlib"), or, the user could choose
a locally provided library instead.




************
2. CONTENTS:
************


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

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 envoke Makefile(s) in subdirectories.  

-- in subdirectory share:
   Make.flags:        Include file for Makefile, to setup Flags, etc.
   Make.local.sample: Include file for Makefile, to setup non-conventional,
                      site specific locations.

-- in subdirectory lsode:
   Copy of README
   lsode_test.out : Reference for test  
   Sources to build library liblsode.a and test program:
   *.f, *.F, *.c, *.h

-- in subdirectory lsode_linpack:
   Sources to build library liblsode_linpack.a:
   *.f

-- in subdirectory portlib:
   Sources to build internally used library libportlib.a:
   *.F, *.f9f, *.c, *.h

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


**************************
3. UNPACKING INSTRUCTIONS:
**************************
Note: Download the module(s) into an empty directory.

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

or, for zip archives:
  > unzip lsode.zip


****************
4. 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:
./lsode         --  sources and Makefile
./lsode_linpack --  sources and Makefile
./portlib       --  sources and Makefile  
./share         --  include file Make.flags 


The location of the following subtrees, containing binaries, can be
controlled via environment variable "OBJ".
   
test              : test program and reference
lib               : the actual library modules
obj/lsode         : temporary for objects and preprocessed sources
obj/lsode_linpack : temporary for objects and preprocessed sources
obj/portlib       : temporary for objects and preprocessed 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, $OBJ/obj 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=.



*************************
5. BUILDING INSTRUCTIONS:
************************* 

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

Required Libraries:
--------------------  
For linking the BLAS library is required.

> gmake            -- to build/link library and lsode_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.

To usr debugger:
> gmake all DEBUG=y

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

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


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

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

cd <MACHINE>/test  or  cd $OBJ/test
./lsode_test -- this program is extracted from the odepack demo test.    
                An example of what its output should
                look like is shown in lsode_test.out


**********************
6. 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/transp.

The assumptions are:

libraries in:        $PREFIX/lib        = $LIBDIR       
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 INCLDIR=yyy MANDIR=/zzz

NOTE:
-----
The libraries are installed as liblsode.a and liblsode_linpack
Users should link with

-L<PREFIX>/lib -llsode -llsode_linpack

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.

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



