README file for Frantic Module

Prepared by C.Ludescher -- ludescher@pppl.gov 12/04/02

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

  Dec 04, 2002  --  Created

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


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


************
1. CONTENTS:
************
The directory into which frantic{zip,tar.gz} was extracted, should contain
the following files:

For FRANTIC:
===========
README_Frantic: This file.  Brief descriptions of the other files, and
                instructions for compiling, testing and installing the
                frantic library libfrantic.a and its test drivers
                test_frantic and geqxpl{2} and the utility plot_frantic. 

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

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

-- in subdirectory include/fpreproc:
   *.h files for source pre-processing.

-- in subdirectory frantic:
   README: Copy of README_frantic
   USERGUIDE
   Makefile
   Sources to build the library libfrantic.a
   Sources for test program:
   	frantic_test.f90 

   Sample input/output files for test:
  	 *.cdf *.ref

-- in subdirectory portlib:
   Makefile
   Sources to build internally used library libportlib.a.

-- in subdirectory prefpp:
   Makefile 
   Sources to build prefpp and postfpp, the Fortran pre- and post-processors.

-- 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.
   
For PREACT:
==========
-- in subdirectory adpak:
   Makefile 
   Sources to build libadpak.a, an internally used library
	to calculate ionization and radiation rates.        

-- in subdirectory aladdinsub:
   Makefile 
   Sources to build libaladdinsub.a, an internally used library
	for Aladdin format.        
     
-- in subdirectory comput:
   Makefile 
   Sources to build libcomput.a, an internally used library 
	with transformation/interpolation routines.

-- in subdirectory cppsub:
   Makefile 
   Sources to build libcppsub.a, a fortran-c++ wrapper

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

-- in subdirectory fpreact:
   Makefile 
   Sources to build libfpreact.a, the f90 interface.

-- in subdirectory include:
	ALCOM		Common block for Aladdin cross-section database.
	ALPCOM  	Common block for Alpack standard Aladdin entry parsing.
	SIGTABL	        Common block for cross-section computation routines.
	SIGTABL_Z	Common block for modified cross-section computation.

-- in subdirectory include/fpreproc:
   *.h files for source pre-processing.

-- in subdirectory include/preact:
   *.h Interfaces for F77 reaction routines and Macros for reaction classes.

-- in subdirectory portlib:
   Makefile
   Sources to build internally used portability library libportlib.a.


-- in subdirectory preact:
   README
   Makefile		   To compile libraries and programs
   ORNL6086.DAT		   Aladdin cross-section data.
   USERGUIDE               Detailed description of code.
   Sources to build the library libpreact.a
       *.cpp               Implementation of reaction classes
       *_z.f               Modified sources from TRANSP comput and sigsub
       icode_preact.f      Return code.

   Sources for programs:
	fpreact_test.f90   Test driver for F90 layer atop PREACT module.
	preact_change.cpp  Changes the parameters of a reaction table.
	preact_init.cpp	   Initializes table parameters for each reaction.
	preact_list.cpp	   Lists table parameters for a particular reaction.
	testpreact.cpp	   Test driver for F77 layer atop PREACT module.
	testf77layer.f	   Test driver for PREACT module.

   preactinit	           Script clears and re-initializes reaction tables.
   fpreact_test.output     Sample output from fpreact_test

-- in subdirectory sigsub:
   Makefile 
   Sources to build libsigsub.a, an internally used
	library with cross-section routines for atomic and nuclear
        reactions.
   

Fore PSPLINE:
============
-- in subdirectory ezcdf:
   Makefile
   Sources to build the library libezcdf.a
 
-- in subdirectory pspline:
   Makefile
   Sources to build the library libpspline.a

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

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

or, for zip archives:
  > unzip frantic.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:
For Frantic
./fpreproc          --  scripts for pre-processing of fortran
./frantic           --  1d neutral gas transport for tokamak core plasmas
./include/fpreproc  --  *.h files for cpp
./prefpp            --  Fortran pre/post processor
./portlib           --  portability routines
./share             --  include file Make.flags, Make.local.sample

For preact
./adpak             --  to calculate ionization and radiation rates
./aladdinsub        --  ORNL Atomic Physics Data Center
./comput            --  low level TRANSP routines
./cppsub            --  fortran c++ wrapper
./include           --  include files for sigsub and alladinsub
./include/fpreproc  --  *.h files for cpp
./include/preact    --  *.h files for preact
./preact            --  sources and Makefile
./prefpp            --  Fortran pre/post processor
./r8slatec          --  double precision "Fullerton" functions
./sigsub            --  atomic/nuclear cross sections integration

For pspline
./pspline          --  Spline and Hermite Cubic Interpolation 
./ezcdf            --  Easy Interface for netCDF Routines

The makefile will create more sub directories,

lib:     for the library, libfrantic.a
mod:     for the f90 modules
obj/*:   for compiled objects and pre-processed sources
test:    for the test program and the sample output file.

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

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

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

Required Libraries:
===================
           netCDF         -  network Common Data Form

Check with your systems administrator where these libraries and modules are.


netCDF
------
netCDF is assumed to be in /usr/local/lib,
if not, you can specify the location with LIBROOT,

e.g.: "gmake LIBROOT=/usr/contrib".

Alternatively you can modify Make.local.sample
and rename it to Make.local.

pspline and preact
------------------
If your site already has pspline and preact libraries installed,
specify their location (library and modules) with PREFIX, 

e.g. "gmake PREFIX=/usr/ntcc"

At PPPL these libraries are in /usr/ntcc.

Note: the Makefile will re-build pspline and preact only if your
      existing version is older.  


Building libraries and programs
-------------------------------- 
> 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.
 
> gmake clean      -- to remove objects
> gmake realclean  -- to remove objects and library

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

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

By default the Makefile will select LaheyFujitsu.

To select a different compiler define
FORTRAN_VARIANT to "Portland"  "NagWare"  "Fujitsu" 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 " -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. TESTING INSTRUCTIONS:
************************

directory $OBJ/test  -or-  <MACHINE>/test  will contain the following
frantic related files:

frantic_test              :  test driver for frantic
frantic_src_0{1,2}.cdf    :  test data
frantic_output_0{1,2}.ref : reference output

To run test:
============
The location of the fusion reaction tables, PREACTDIR, must
be defined and the tables must be initialized.
See http://w3.pppl.gov/NTCC/PREACT
or preact/USERGUIDE and REDAME (included in the preact module).

cd <MACHINE>/test
./frantic_test frantic_src_01.cdf > my_01.out

diff my_01.out frantic_output_01.ref

same with 2nd example.

For instructions on how to use the library routines in your own code
see USERGUIDE (supplied with distribution, or on web
http://w3.pppl.gov/NTCC/FRANTIC/USERGUIDE).


************************
6. DOCUMENTATION:
************************

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


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


**********************
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 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  
    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 MODDIR=yyy MANDIR=zzz

NOTE:
-----
To link a program, you need all frantic, pspline and preact libraries.
e.g:

-L<PREFIX>/lib -lfrantic -lfpreact -lpreact \
         -lsigsub -laladdinsub -adpak -cppsub \
	 -lpspline -lezcdf -lcomput -lportlib

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, Princeton University
                cludescher@pppl.gov
        or      
                ntcc_webmaster@pppl.gov




