README file for Xplasma Module

Prepared by C.Ludescher-Furth -- ludescher@pppl.gov 06/26/00

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

  June 26, 2000  -- Created
  Feb. 08, 2001  -- Support of EFIT output
  June 21, 2001  -- Added geqxpl2 sample program
  Mar. 14, 2006  -- Added xplasma_fsp_test example
  Sep. 08, 2006  -- New xplasma2
----------------------------------------------------------------


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


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

README_Xplasma: This file.  Brief descriptions of the other files, and
                instructions for compiling, testing and installing the
                libxplasma2, old_xplasma, xplasma_debug libraries,
                and the test drivers xplasma2_test,
                test_xplasma, xplasma_fsp_test and geqxpl{2}
                and the utility plot_xplasma. 

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 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 xplasma:
   Copy of README
   Makefile
   Sources to build the library libxplasma.a
	*.f, *.F, *.F90
   Sources for programs:
   	test_xplasma.f90, plot_xplasma.f, geqxpl[2}.for
	xplasma_fsp_test.f90 xplasma2_test.f90

   Sample input/output files for test:
  	 *.ind, *.treq_data script_output.ps, g*.nstx 
         104276D02_4s710_xplasma.cdf

-- in subdirectory comput:
   Makefile 
   Sources to build libcomput.a, an internally used library 
	with transformation/interpolation routines.
   
-- in subdirectory fluxav:
   Makefile 
   Sources to build libfluxav.a, an internally used library 
	for flux zone / flux surface averages and integrals.

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

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

-- in subdirectory mclib:
   Makefile 
   Sources to build libmclib.a, an internally used library 
	for string manipulation.
   
-- in subdirectory r8bloat:
   Makefile 
   Sources to build libr8bloat.a, an internally used library 
	with miscelanious math routines.
   
-- in subdirectory smlib:
   Makefile 
   Sources to build libsmlib.a, an internally used library 
	with math routines.
      
-- in subdirectory tridiag:
   Makefile 
   Sources to build libtridiag.a, an internally used library
	for solving tridiagonal systems.

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

-- for the test and the visualization programs:
   subdirectories sglib, trgraf, ureadsub, vaxonly, lsode,
	lsode_linpack, mdstransp, nscrunch
   	containing sources and Makefiles to build these libraries.

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

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

or, for zip archives:
  > unzip xplasma.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:
./xplasma2          --  sources and Makefile
./old_xplasma       --  sources and Makefile
./xplasma_debug     --  sources and Makefile
./comput            --  transformation/interpolation routines
./fluxav            --  flux zone / flux surface averages and integrals
./fpreproc          --  scripts for pre-processing of fortran
./geqdsk_mds        --  
./include/fpreproc  --  *.h files for cpp
./lsode             --  REAL*8 version of netlib odepack
./lsode_linpack     --  linpack routines used by lsode
./mclib             --  string manipulation
./mds_dummy         --  Dummy routines for mdsplus
./mdstransp         --  fortran/c interface for mdsplus
./nscrunch          --  moment representation of nested flux surfaces
./portlib           --  internally used library
./r8bloat           --  miscelanious math routines
./share             --  include file Make.flags, Make.local.sample
./smlib             --  math algorithms
./tridiag           --  for solving tridiagonal systems
./vaxonly	    --  Low level code for machine dependence

for test_xplasma and visualization program:
./sglib             -- graphics 
./trgraf	    -- display routines
./ureadsub          -- interactive command interface 


The makefile will create more sub directories,

lib:     for the libraries
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 Libraries:
===================
           libpspline.a   -> NTCC module PSPLINE, now on GitHub
           lapack
	   blas
           netCDF


Optional Libraries:
===================
           MDSplus   for geqxpl option 

	   readline, history, termcap  for Command Line Editing
           Note: if these libraries are "partionally" installed,
                 not all three are available, 
                 you must define NO_EDITLIBS
		 e.g.: gmake NO_EDITLIBS=Y

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


lapack, blas and netCDF
-----------------------
lapack, blas 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
-------
If your site already has pspline installed,
specify the location (library and modules) with PREFIX, 

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

At PPPL ntcc libraries are in /usr/ntcc.

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


Building libraries and proprams
-------------------------------- 
> 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 Fujitsu f95.

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

Note: some test programs are linked with g++; to find the Fortran libraries,
      you need to define FLIBROOT

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:

xplasma2_test    :  Quick test of xplasma

test_xplasma     :  Test driver for xplasma 
script.ind       :  controlling input script for test_xplasma
jet.ind		 :  input script for script.ind
nstx.ind         :  input script for script.ind
plotall.ind
script_output.ps :  output from "test_xplasma @script"

geqxpl           :  Test for EFIT output
nstx_geqdsk.ind  :  controlling input script for geqxpl
g104403.nstx     :  a G-EQDSK file
geqxpl_output.ps :  output from "geqxpl @nstx_geqxpl"

geqxpl2          :  Example to create an xplasma from a geqdsk file
g103875.nstx     :  a G-EQDSK file

xplasma_fsp_test :  Examples for F77 interface calls
104276D02_4s710_xplasma.cdf : input for xplasma_fsp_test

plot_xplasma     :  visialization utility


To run tests:
-------------
define environment variable TERMINAL_TYPE = XTERM
 (e.g. export TERMINAL_TYPE=XTERM)

cd <MACHINE>/test
./xplasma2_test

No input required. 

./test_xplasma @script

This will produce a canned sequence of plots.  This is the same set of
plots as are stored in script_output.ps

./geqxpl @nstx_geqdsk

This will also produce a canned sequence of plots.  This is the same set of
plots as are stored in geqxpl_output.ps

./geqxpl2

This will start an interactive session.


./xplasma_fsp_test

This will read the includes netCDF file and print the example results.
(no graphics).

For details see README or http://w3.pppl.gov/~pshare/help/xplasma.htm


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

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

XPLASMA HELP
http://w3.pppl.gov/~pshare/help/xplasma.htm

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
utility in:         $PREFIX/bin        = $BINDIR
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 BINDIR=zzz

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

-L<PREFIX>/lib -lxplasma -lfluxav -lezcdf \
	 -lmclib -lsmlib -ltrgraf -lureadsub -lvaxonly  \
	 -ltridiag -lr8bloat -lcomput -lpspline -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




