README file for Nubeam Module

Prepared by C.Ludescher-Furth -- ludescher@pppl.gov 03/25/02

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

  Mar 25, 2002  -- Created
  Oct 01, 2003  -- Added nubeam_driver
  Jan 11, 2009  -- replaced nubeam_driver with (mpi_}nubeam_comp_exec
                   for parallel build define MPI_ENABLE=1
----------------------------------------------------------------


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 nubeam{zip,tar.gz} was extracted, should contain
the following files:

README_Nubeam: This file.  Brief descriptions of the other files, and
                instructions for compiling, testing and installing the
                nubeam library libnubeam.a and its test drivers
                test_nubeam and geqxpl{2} and the utility plot_nubeam. 

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 kdsaw:
   Makefile 
   Sources to build kdsaw.a, an internally used library 
   for the ideal Kadomtsev Sawtooth Model.
   
-- in subdirectory nbdebug:
   Makefile 
   Sources to build nbdebug.a, a library for nubeam_test 


-- in subdirectory nubeam:
   README: Copy of README_nubeam
   UserGuide
   Makefile, Make2
   Sources to build the library libnubeam.a
   Source for test program:
   	nubeam_test.f90

   Sample input/output files for nubeam_test:
  	 *.ind, sample_run_*, *.cdf 

   Sample input/output files for nubeam_driver:
  	 *.CDF, nubeam*.dat, nubeam*.ref

-- in subdirectory nubeam_comp_exec:
   README, README_PPL
   Makefile, Make2 
   Sources to build nubeam_comp_exec and mpi_nubeam_comp_exec 
   Sample input/output files
   scripts for testing

-- in subdirectory nubeam_comp_sub:
   Makefile
   Sources to build nubeam_comp_sub.a, library for nubeam_comp_exec 

-- in subdirectory portlib:
   Makefile, Make2
   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 random:
   Makefile 
   Sources to build librandom.a, an internally used library 
   to generate random numbers.

-- 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 xstraln:
   Makefile 
   Sources to build libxstraln.a, an internally used library for 
   straight line tracker.
   
And for Test Program:

-- in subdirectory trgraf:
   Makefile and sources to build libtrgraf.a, a display library.
-- in subdirectory  ureadsub
   Makefile and sources to build libureadsub.a, an input interface.

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

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

or, for zip archives:
  > unzip nubeam.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:
./fpreproc          --  scripts for pre-processing of fortran
./frantic           --  1d neutral gas transport calculation 
./get_fbm_kernel    --  for get_fbm
./get_fbm_xplasma   --  get distribution functions
./include/fpreproc  --  *.h files for cpp
./interp_sub        --  linear or bilinear interpolation of gridded data
./kdsaw             --  Kadomtsev Sawtooth Model
./mds_sub           --  interface to mdsplus
./nbdebug           --  routines for nubeam_test
./nubeam            --  Monte Carlo package of fast ion species in tokamaks
./nubeam_comp_exec  --  nubeam driver and test samples
./nubeam_comp_sub   --  routines for nubeam_comp_exec
./plasma_state      --  representation of fusion plasma MHD equilibrium 
./plasma_state_kernel - for plasma_state
./plot_fpreact      --  data plotting routines
./portlib           --  portability routines
./ps_xplasma2       --  plasma state / xplasma interface
./r8slatec          --  Fullerton functions
./random            --  random number generator
./rfxqlo            --  Fokker Planck / wave solver interface 
./rfxqlo_helper     --  
./share             --  include file Make.flags, Make.local.sample
./sglib             --  graphical library for test programs
./trgraf            --  display routines for test program
./ureadsub          --  input routines for test program
./xstraln           --  xplasma based straight line tracker

The makefile will create more sub directories,

lib:     for the library, libnubeam.a
mod:     for the f90 modules
obj/*:   for compiled objects and pre-processed sources
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/...

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 Compilers:
===================
           Fortran 90 or 95
           C and C++
    >>>>>  you need gcc 3.X or a reasonable C++ standard

Required Libraries:
===================
           libxplasma.a   -> NTCC module Xplasma
           libpspline.a   -> NTCC module PSPLINE   
           libpreact.a    -> NTCC module PREACT

           lapack         -  Linear Algebra PACKage
	   blas           -  Basic Linear Algebra Subprograms
           netCDF         -  network Common Data Form
           fftw		  -  fast fourier transforms 
   For nubeam_driver:
           trread.a       -> NTCC module TRREAD

Optional Libraries:
===================
	   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

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


lapack, blas, fftw, netCDF
---------------------------
lapack, blas, fftw and netCDF are assumed to be in /usr/local/lib,
if not, you can specify the location with LIBROOT,

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

If netCDF is in a separate location, specify NETCDF_DIR

e.g.: "gmake NETCDF_DIR=/usr/local/my-netcdf LIBROOT=/my-libroot".

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

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

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

At PPPL these libraries are in $NTCCHOME

Note: If you don't have all required NTCC libraries, you may download
      them together into the same work directory. The Makefile will build
      them all in one step. 


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


To compile the MPI version, define environment MPI_ENABLE
e.g.: setenv MPI_ENABLE 1

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

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

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.

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-  <MACHINE>/test  will contain the following
nubeam related files:

For nubeam_test:
----------------
sample_run.csh       :  script to run nubeam_test
nubeam_test          :  test driver for nubeam
sample_run.ind       :  controlling input script for nubeam_test

sample_run_output.ps :  output from "nubeam_test @sample_run"
                        in PS format
sample_run_output.txt:  output from "nubeam_test @sample_run"
                        in text format
sample_run_alpha.txt :  output from "nubeam_test @sample_run"
                        from a Alpha Linux machine in text format

For {mpi_}nubeam_comp_exec
---------------------------
See nubeam_comp_exec/README and README_PPL
 
To run tests:
=============
define environment variable TERMINAL_TYPE = XTERM
 (e.g. export TERMINAL_TYPE=XTERM)

Also, 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

nubeam_test
-----------
./nubeam_test @sample_run

   This will produce a canned sequence of plots.  This is the same set of
   plots that is stored in sample_run_output.ps (e.g., running ghostview on
   sample_run_output.ps should produce identical plots.)

You can also run:
./sample_run.csh

   This will produce the PS file,foo.ps and a text file foo.txt.
   foo.ps can be compared with sample_run_output.ps, and 
   foo.txt with sample_run_output.txt. 

For instructions on how to use the library routines in your own code
see UserGuide on the web
http://w3.pppl.gov/NTCC/NUBEAM
or
http://w3.pppl.gov/~pshare/help/nubeam.htm


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

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


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 nubeam, xplasma, pspline and preact
libraries.

e,g:

-L<PREFIX>/lib -lnubeam -lkdsaw -lxstraln -lfpreact -lpreact \
         -lsigsub -laladdinsub -lxplasma -lfluxav -lmclib -lsmlib -ltridiag \
         -lr8bloat -lpspline -lezcdf \
         -lcomput -lvaxonly -lrandom -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-Furth, Princeton University
                cludescher@pppl.gov
        or      
                ntcc_webmaster@pppl.gov




