README file for NTCC Module rplot

Prepared by C.Ludescher-Furth -- ludescher@pppl.gov 05/22/02

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

  May. 20, 2002  -- Created 

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


Index:
   1. CONTENTS
   2. UNPACKING INSTRUCTIONS
   3. DESTINATIONS
   4. BUILDING INSTRUCTIONS
   5. TESTING INSTRUCTIONS
      5.A. To produce a PostScript file
   6. DOCUMENTATION
   7. FINAL INSTALLATION


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

README_Rplot: This file.  Brief descriptions of the other files, and
                instructions for compiling, testing and installing rplot. 

Makefile:       NOTE: "GNU make" must be used
                      (usually in /usr/gnu/bin or /usr/local/bin).
                      You also need "gcc" for pre-processing (exept on CRAY).
		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 rplot:
   Copy of README
   Makefile
   Sources to build the program rplot

-- in subdirectories rp_kernel, rplot_io:
   Makefile 
   Sources to build librp_kernel.a and librplot_io, internally used
	libraries to handle RPLOT i/o.
   
-- in subdirectory mdstransp:
   Makefile 
   Sources to build libmdstransp.a, an internally used library
	with trans-Mdsplus interfaces.

-- in subdirectory smlib:
   Makefile 
   Sources to build libsmlib.a, an internally used library 
	with math routines.
   
-- in subdirectory xdatmgr:
   Makefile 
   Sources to build libxdatmgr.a, an internally used library
	for memory management.

-- in subdirectory vaxonly:
   Makefile 
   Sources to build vaxonly.a, an internally used library
	with miscellaneous routines.

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

-- in subdirectory interp_sub:
   Makefile 
   Sources to build libinterp_sub.a, an internally used library 
	with interpolation routines.

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

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

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

-- in subdirectories rplot_sub, ureadsub, trgraf, sgdummy:
   Makefile
   Sources to build libraries needed by rplot.


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

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

or, for zip archives:
  > unzip rplot.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:
./rplot             --  sources and Makefile
./share             --  include file Make.flags, Make.local.sample
./portlib           --  internally used library
./include/fpreproc  --  *.h files for cpp
./fpreproc          --  scripts for pre-processing of fortran
./rp_kernel         --  RPLOT i/o
./rplot_io          --  RPLOT i/o
./mdstransp         --  MDSplus interface  
./smlib             --  math algorithms
./interp_sub        --  interpolation routines
./comput            --  transformation/interpolation routines
./xdatmgr           --  memory management
./vaxonly           --  miscellaneous
./sglib             --  Scientific Graphics Library

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

The makefile will create more sub directories,

lib:     for the libraries
mod:     for fortran 90 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:
===================
       gcc        -- for pre-processing (exept on CRAY)
       Fortran 90
       C

Required Libraries:
===================
	MDSplus 
        netCDF   -- for cdfcon and test program

Check with your systems administrator where these libraries and modules are.
Defaults are /usr/local/mdsplus/lib and /usr/local/lib.

Define MDSPLUS_DIR or 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


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

By default the Makefile will select Fujitsu f95.

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

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.



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

directory $OBJ/test  -or-  <MACHINE>/test  will contain: rplot

To test rplot:
---------------

define environment "TERMINAL_TYPE" XTERM
 (e.g. export TERMINAL_TYPE=XTERM)

cd <MACHINE>/test
./rplot   --  to get an interactive menu

or, you can type ahead:
./rplot t s transpgrid.pppl.gov y ITER.01 q 03000A38 pheat


----------------------------------
5.A. To produce a PostScript file: 
----------------------------------
define environment "PLOT"
 (e.g. export PLOT=',foo.plt-ps')
 See http://w3.pppl.gov/transp
     SGLIB Help  - PPPL Scientific Graphics library
     Logical_variables

 Note: tek2ps_sh and tek2ps must be in your $PATH
       tek2ps.pro should be in $cwd or in $TRANSP_LOCATION


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

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

TRANSP Home Page
http://w3.pppl.gov/transp
  Help Documents and Manuals 
  - Transp Help  - set up TRANSP runs and use RPLOT
  - SGLIB Help   - PPPL Scientific Graphics library
  - TEK2PS Help  - Converts tektronix plot files into Postscript


**********************
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
executacles in:    $PREFIX/bin          = $BINDIR
man pages in:      $PREFIX/man/man{1,3} = $MANDIR/man{1,3}

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 BINDIR=/xxx MANDIR=zzz

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




