README file for NTCC Module TrRead

Prepared by C.Ludescher -- ludescher@pppl.gov 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. DOCUMENTATION
   7. FINAL INSTALLATION


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

README_TrRead: This file.  Brief descriptions of the other files, and
                instructions for compiling, testing and installing the
                trread library libtrread.a and its test driver
                trread_test. 

Makefile:       NOTE: "GNU make" must be used
                      (usually in /usr/gnu/bin or /usr/local/bin).
                      You also need python for pre-processing.
		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 trread:
   Copy of README
   Makefile
   Sources to build the library libtrread.a
	*.f, *.F, *.F90
   Sources for programs:
	cdfcon.F         -- creates CDF file from transp run
   	trread_test.f    -- for testing

   Sample input/output files for test:
  	11114p04.cdf, 11114p04tr.dat
	expected_trread_test.msg, expected_trread_test.output

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


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

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

./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:
===================
       Python        -- for pre-processing 
       Fortran 90
       C

Required Library:
===================
        netCDF   -- for cdfcon and test program
        
Note: Ignore complaints about ezcdf - you probably don't need it.

Check with your systems administrator where the library.
Default is /usr/local/lib.

You can define non-standard locations via NETCDF_DIR and MDSPLUS_DIR.

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 " -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:

trread_test                 :  Test driver for trread
11114p04.cdf		    :  transp run output
11114p04tr.dat              :  transp namelist 
expected_trread_test.msgs   :  sample of output messages 
expected_trread_test.output :  sample of output 

To run test:
-----------

cd <MACHINE>/test
./trread_test.csh

This will produce trread_test.output and trread_test.msgs and compare it.
Due to architecture differences you might prefer running  ./trread_test
and do the compare manually.


For details see http://w3.pppl.gov/~pshare/help/trread.htm


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

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

TrRead HELP
http://w3.pppl.gov/~pshare/help/trread.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
executacles in:    $PREFIX/bib          = $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 LIBDIR=/xxx MANDIR=zzz

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

-L<PREFIX>/lib -ltrread -lrp_kernel -lrplot_io -lxdatmgr -lmdstransp -linterp_sub -lsmlib -lcomput -lvaxonly -lportlib $MDSLIB.

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




