README file for PREACT Module

Prepared by C.Ludescher-Furth -- 08/03/00

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

  Aug. 03, 2000  -- Created

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


Index:
   1. CONTENTS
   2. UNPACKING INSTRUCTIONS
   3. DESTINATIONS
   4. BUILDING INSTRUCTIONS
   5. TESTING INSTRUCTIONS
   6. FINAL INSTALLATION
   7. RE-INITIALIZING REACTION TABLES
   8. DOCUMENTATION

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

README_Preact:  This file.  Brief descriptions of the other files, and
                instructions for compiling, testing and installing the
                preact library libpreact.a and its test drivers
                testpreact and testf77layer. 

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 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.
	ULOGICAL	Common block for 'UREAD' logical function declarations.

-- 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: Copy of README_preact
   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 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.

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

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

or, for zip archives:
  > unzip trread.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:

./adpak             --  to calculate ionization and radiation rates
./aladdinsub        --  ORNL Atomic Physics Data Center
./comput            --  low level TRANSP routines
./cppsub            --  fortran c++ wrapper
./fpreproc          --  scripts for pre-processing of fortran
./include           --  include files for sigsub and alladinsub
./include/preact    --  *.h files for preact
./include/fpreproc  --  *.h files for cpp
./portlib           --  internally used portability library
./preact            --  sources and Makefile
./prefpp            --  Fortran pre/post processor
./share             --  include file Make.flags, Make.local.sample
./sigsub            --  atomic/nuclear cross sections integration



The makefile will create more sub directories,

${OBJ}/lib	     	for the libraries
${OBJ}/obj/*	   	for compiled objects and pre-processed sources
${OBJ}/test   		for the test programs and utilities
${PREACTDIR}/data       for Aladdin cross-section data.
${PREACTDIR}/tables/*  	Directory structure for precomputed reaction tables.

You must define the environment PREACTDIR. The data and tables are
independent of architecture, so everyone can access the same tables. 

By default ${OBJ} is  ./<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/...

Note: ${OBJ} is platform dependent, whereas ${PREACTDIR} is not.
 
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:
*************************

>>> Note <<<
To compile this code, you'll need gcc 3.X or a reasonable C++ compiler.


Building libraries, proprams and tables
---------------------------------------

Choose or create the root directory where you wish to build the 
Plasma Reaction Tables. Set the environment variable PREACTDIR to be
the full pathname of the directory where the Tables will be stored.
The Makefile will initialize the Tables after buiding the test programs.

From the top directory (where you extracted the {tar,zip} file):
 
> gmake            -- to compile libraries, link all test programs
                      and initialize tables

> gmake clean      -- to remove objects
> gmake realclean  -- to remove objects and library


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

By default the Makefile will select Fujitsu f95.

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

Note: By default the test programs, nubeam_test and nubeam_driver,
      are linked with lf95. If you encounter a problem, try linking with g++:

> gmake USEFC=N 


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

Therefor 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.
Therefor 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:

    preact_change	Changes the parameters of a particular reaction table.
    preact_init		Initializes table parameters for each reaction.
    preact_list		Lists table parameters for a particular reaction.
    testpreact		C++ test driver for PREACT module.
    testf77layer	Test driver for F77 layer atop PREACT module.
    fpreact_test	F90 test driver using the fpreact interface.
    fpreact_test.output Sample output of fpreact_test

To run tests:
-----------

(a) If PREACTDIR was defined during Step 4. go to (b). 
    If you did not define PREACTDIR during step 4., you must now define it
    and manually initialize the Tables with
	cd <MACHINE>/test
	preactinit


(b) Test
cd <MACHINE>/test

   - to run the C++ test driver
	./testpreact

   - to run the fortran test driver
	./testf77layer

Both programs perform identical tasks, creating/reading a subset of tables.
The 1st time run, it will be slow, since the tables have to be created.
The 2nd time should be quite fast, since it is only reading.

   - to run the fortran 90 test driver
	./fpreact_test

This program is similar to the other two.
You can compare the output (when run the 2nd time) to fpreact_test.output.


For details see USERGUIDE, included in this distribution.


**********************
6. FINAL INSTALLATION:
**********************

There are two distinct parts to be installed:

 ->  The Plasma Reaction Tables (in ascii format) in $PREACTDIR.
 ->  The architecture dependent libraries and utilities in $PREFIX.

(a) $PREACTDIR
    Choose or create the root directory where you wish to build the 
    Plasma Reaction Tables. Set the environment variable PREACTDIR to be
    the full pathname of the directory where the Tables will be stored.  
    For example, if you want to keep it in a subdirectory 'preact' of your
    home directory, then you should define PREACTDIR $HOME/preact.

    The tables will be created in:
	$PREACTDIR/data
	$PREACTDIR/tables/{cx,ii,fs}/*/*

    Note: The installation is not going to build all the tables, it is only
          creating a scelleton. The Tables will be created on demand.
          Therefore PREACTDIR must grant write access to all potential users. 

(b) $PREFIX
    Choose or create the root directory where you wish to install the 
    libraries, executables and man page. Common locations would be 
    $HOME/<architecture> or /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
    executables in:     $PREFIX/bin        = $BINDIR
    scripts in:         $PREFIX/etc        = $ETCDIR
    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 BINDIR=yyy MANDIR=zzz

NOTE:
-----
Users should link with:

-L<PREFIX>/lib -lpreact -lsigsub -laladdinsub -lpreact -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.


**********************************
7. RE-INITIALIZING REACTION TABLES
**********************************

To initalize new tables, you can run the script preactinit.
You need to provide the location of the Aladdin cross-section data,
ORNL6086.DAT, that came with the package in the preact directory.

1. define $PREACTDIR (see Section 6. FINAL INSTALLATION)

2. run preactinit 
   preactinit will run preact_init, so if both are in your PATH, 
   type:
   > preactinit DATA <dir of ORNL6086.DAT>
 
   If preact_init is not in your PATH, type
   > preactinit DATA $HOME/ntcc/preact PATH <path of preact_init>

   for options see also: 
   > preact help

   Note: you can re-use ORNL6086.DAT from a previous installation,
   by specifying "DATA <old_preactdir>/data"

************************
8. DOCUMENTATION:
************************

See USERGUIDE, part of this distribution.

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

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



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

IF YOU HAVE ANY PROBLEMS, PLEASE CONTACT EITHER:

        TRANSP Support - transp_support@pppl.gov

	Princeton Plasma Physics Laboratory
