README file for Tr_Start Module

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

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

  Mar 29, 2002  -- Created

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


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


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

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

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 tr_start:
   Copy of README
   UserGuide
   Makefile
   Sources for programs:
      mds_start.F, set_yr.f

   Scripts:
      tr_start          --   PPPL customized script to run tr_start.pl 
      tr_start.pl       --   create MDSplus pulse, write Input data
	        	     and generate <runid>.REQUEST file
      tr_send           --   PPPL customized script to run tr_send_pppl.pl
      tr_send_pppl.pl   --   send<runid>.REQUEST and PBS submit run
      tr_cleanup        --   PPPL customized script to run tr_send_cleanup
      tr_send_cleanup   --   cleanup all remains of a run
      tr_look           --   script to ask for intermittent output
      tr_status         --   inquire status of a run
      tr_fetch          --   fetch TRANSP output
      trdat.pl          --   script to generate node names from namelist
                             for mds_start.
      transp_tree.tcl   --   tcl script to create a TRANSP Model Tree
      tr_griduserproxy_send  -- script to send new proxy

-- in subdirectory etc:
   Data files for mds_start:
      trdat.list        --   for trdat.pl 	  
      TOKAMAK.DAT       --   list of tokamaks

-- in subdirectory TFTR/test:
   sample TRANSP input files for testing

-- in subdirectory mds_sub:
   Makefile 
   Sources to build mds_sub.a, an internally used library 
   for mds_start.

-- in subdirectory mdstransp:
   Makefile 
   Sources to build libmdstransp.a, an internally used library
	with trans-Mdsplus interfaces.
   
-- in subdirectory uflib:
   Makefile
   Sources to build internally used library libuflib.a.
	to read ufiles.

-- in subdirectory ufhdf:
   Makefile
   Sources to build internally used library libufhdf.a.
	to read ufiles of netCDF/ HDF formats.

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

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

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

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

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

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

or, for zip archives:
  > unzip tr_start.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:
./tr_start          --  sources, scripts and Makefile
./share             --  include file Make.flags, Make.local.sample
./include/fpreproc  --  *.h files for cpp
./fpreproc          --  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

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
           

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/mdslib/lib,
otherwise define MDSPLUS_DIR.
if not, modify MDSLIB in share/Make.local
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)
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:
Scripts, executables and a sample Namelist.

For testing (prior to final installation)

I. using the sample 37065Z01:
-----------------------------
   1. Define Environment Variables:
      - MDS_TRANSP_SERVER
        If you don't use Mdsplus, define =  NONE.

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

   4. Submit/Launch the run:
      A. If you use mdsplus:
         tr_send 37065Z01
     
      B. If you don't use mdsplus:
         tr_send_pppl.pl 37065Z01 TFTR NOMDSPLUS

   5. See status on http://w3.pppl.gov/cgi-bin/transpgrid_monitor

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


************************
6. DOCUMENTATION:
************************
TRANSP Home Page
http://w3.pppl.gov/transp


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


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:


programs in:        $PREFIX/bin        = $BINDIR
scripts in:         $PREFIX/etc        = $ETCDIR
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 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 EITHER:


        Doug McCune, Princeton University
                dmccune@pppl.gov
        or

        Christiane Ludescher-Furth, Princeton University
                cludescher@pppl.gov
        or      
                ntcc_webmaster@pppl.gov




