README file for TR_Client Module

Prepared by C.Ludescher-Furth -- 01/29/03

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

  Jan 29, 2003  --  Created

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


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


************
1. CONTENTS:
************
Note: See README_TrStart and README_rplot for details on tr_start and rplot.
      See Notes_mdsplot on how to install mdsplot.

This directory should contain the following files:

README_TrClient: This file.  Brief descriptions of the other files, and
                instructions for compiling, testing and installing
                scruncher, scrunch2, nbfile, adisplay and get_fbm. 

README_TrStart: Brief descriptions of tr_start related files and
                instructions for compiling, testing and installing the
                tr_start scripts, executables and data files. 

README_rplot:  Brief descriptions of rplot related files and
                instructions for compiling, testing and installing
		rplot. 
Notes_mdsplot: Brief descriptions of mdsplot and how to install it.

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 client:
   Copy of README
   UserGuide:         Description of scripts and programs.
   Makefile
   Sources for programs:
      nbfile, nblist, scruncher, scrunch2, mdsplot, adisplay, get_fbm, set_yr
   

-- in subdirectory nblistsub:
   Makefile 
   Sources to build libnblistsub.a, a library to handle input
     to nbfile.

-- in subdirectory momsub:
   Makefile 
   Sources to build libmomsub.a, a library to convert  magnetics
     into TRANSP form for scruncher.

-- in subdirectory scrunch:
   Makefile 
   Sources to build libscrunch.a, a library to map plasma boundary
      into TRANSP usable form for scruncher.

-- in subdirectory scr2lib:
   Makefile 
   Sources to build libscr2lib.a, a library to convert EFIT
       into TRANSP usable form for scrunch2.

-- in subdirectory tftrg1:
   Makefile 
   Sources to build libtftrg1.a, a library used by nbfile.

-- in subdirectory tr_tdi
   PPPL customized tdi functions 

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

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

or, for zip archives:
  > unzip tr_client.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 tr_start:
./tr_start          --  sources, scripts and Makefile for software to start a TRANSP run
./share             --  include file Make.flags, Make.local.sample
./include           --  shared include files for TRANSP libraries
./include/fpreproc  --  *.h files for cpp
./fpreproc          --  python scripts for pre-processing of fortran
./mds_sub           --  ufiles/mdsplus interface
./mdstransp         --  MDSplus interface
./portlib           --  routines for porting
./sgdummy           --  dummy routines for sglib
./uflib             --  to read standard ufiles
./ufhdf             --  to read ufiles of netCDF / HDF format
./ureadsub          --  I/O routines
./vaxonly           --  miscellaneous
./TFTR/test         --  Ufiles for testing
./*_dummy           --  dummy routines for netcdf, hdf

for rplot:
./rplot             --  sources and Makefile
./rp_kernel         --  RPLOT i/o
./rplot_io          --  RPLOT i/o
./rplot_sub         --  RPLOT
./r4smlib           --  math algorithms (smoothing)
./interp_sub        --  interpolation routines
./comput            --  transformation/interpolation routines
./xdatmgr           --  memory management

./trgraf            --  for cdfcon
./sgdummy           --      "

for scruncher, scrunch2
./scrunch           -- map plasma boundary into TRANSP usable form
./momsub            -- converting magnetics analysis into TRANSP form
./scrlib2           -- convert EFIT into TRANSP usable form
for nbfile
./nblistsub         -- prepare neutral beam info
./tftrg1            -- TFTR specific data access routines
for adisplay, get_fbm
./hpsort            -- heap sort
./i3encod           -- ascii encode/decode of floatimg point
./zm_swb            -- ULTRA random number generator

for mdsplot
./tr_tdi            -- PPPL customized MDSplus tdi functions

The makefile will create more sub directories,

lib:     for the library, libtr_start.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 Libraries:
===================
           MDSplus
           
	For scruncher, scrunch2
	   pspline  -- NTCC Module
	   xplasma  -- NTCC Module
	   trxplib  -- NTCC Module (scrunch2 only)

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

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


MDSplus
-------
MdsLib is assumed to be in /usr/local/mdsplus/lib,
otherwise define MDSPLUS_DIR.
If it's not installed properly, modify MDSLIB in share/Make.local

If you don't have MDSplus, build the code with
"make NO_MDSPLUS=1" -or- define environment variable NO_MDSPLUS

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

To select a different compiler define
FORTRAN_VARIANT to "Intel", "Portland",  "NagWare",  "Fujitsu" or "Absoft"

e.g.:
setenv FORTRAN_VARIANT Portland (csh)
export FORTRAN_VARIANT=Portland (bash)

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.

Linking:
--------
Some C programs need to link with Fortran Libraries.
The Makefile is looking in -L$(FLIBROOT)/lib.
Define FLIBROOT or F90HOME to point to your fortran installation,
e.g: export FLIBROOT=/usr/pppl/pgi/6.1-2/linux86/6.1


************************
5. TESTING INSTRUCTIONS:
************************

directory $OBJ/test  -or-  <MACHINE>/test  will contain:
Scripts, executables and a sample Namelist.

For testing (prior to final installation)

I.   Define environment variable MDS_TRANSP_SERVER
     If you don't use Mdsplus, define MDS_TRANSP_SERVER=NONE.

II.  Creating the Pulse and writing the Input
     using the sample NameList 37065A01TR.DAT:

    1. Define Environment Variables:
      - DATADIR <DOWNLOADDIR> 
          where  <DOWNLOADDIR> = the directory where you downloaded the
          {tar,zip}file
      - TRANSP_LOCATION <DOWNLOADDIR>/etc
  
      - PATH
        add <DOWNLOADDIR>/<MACHINE>/test to your PATH
      e.g.: on Linux, if downloaded into $HOME/ntcc
      # setenv DATADIR $HOME/ntcc
      # setenv TRANSP_LOCATION $HOME/ntcc/etc
      # setenv PATH $HOME/ntcc/LINUX/test:$PATH

      Note: After you have installed the package, you must change 
            the Environment accordingly.
 
    2. mkdir <mytest>
      cp $DATADIR/TFTR/test/37065Z01TR.DAT .

    3. tr_start 37065Z01
       To start the run.

III. Submitting the run to PPPL
     1.A. If you use mdsplus:
          tr_send 37065Z01
     
     1.B. If you don't use mdsplus
          tr_send_pppl.pl 37065Z01 TFTR NOMDSPLUS
     

IV.  Running mdsplot
     See Notes_mdsplot

See http://w3.pppl.gov/transp for details.


************************
6. DOCUMENTATION:
************************
UserGuide:
http://w3.pppl.gov/transp/production.html#Tools

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

TRANSP Home Page
http://w3.pppl.gov/transp

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


**********************
7. FINAL INSTALLATION:
**********************
Note: Unless you run your own TRANSP Production System, you do NOT need mdsplot.

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:


programs in:        $PREFIX/bin        = $BINDIR
scripts in:         $PREFIX/etc        = $ETCDIR
libraries in:       $PREFIX/lib        = $LIBDIR
f90 modules:        $PREFIX/mod        = $MODDIR
man pages in:       $PREFIX/man/man3   = $MANDIR/man3

For mdsplot:
tdi functions in:   $TDIDIR 
You must define TDIDIR to a directory that is in your MDSplus Server's MDS_PATH.
 

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

For mdsplot:
> gmake install PREFIX=/dir1/dir2/ TDIDIR=/my/mdsplus/tdi

If you want things elsewhere, you can overwrite the default with
> gmake install ETCDIR=/xxx BINDIR=zzz

NOTE:
-----
Add <PREFIX>{bin,etc} to you PATH.

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:

        TRANSP Support - transp_support@pppl.gov

	Princeton Plasma Physics Laboratory
