           Installation Notes for NTCC module PEST3.2

Prepared by C.Ludescher cludesche@pppl.gov  02/20/2001

================
REVISION HISTORY
================
      date         Description

  Feb 20, 2001  -- Created 

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

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

==========================
1. UNPACKING INSTRUCTIONS
==========================
Note: Download the module(s) into an empty directory.

Unpack the tar file with
    gunzip pest3.2.tar.gz
    tar xvf pest3.2.tar
  or
    unzip pest3.2.zip

============
2. CONTENTS
============
The package should include the following files:

   README_pest3.2      --  description of PEST3.2
   INSTALL_pest3.2     --  this file
   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.

in sub directory pest3.2:
   README            --  copy of README_pest3.2
   INSTALL           --  copy of INSTALL_pest3.2
   Makefile          --  Makefile to build pest3_2 library and tes
   *.f90, *.inc      --  source for library 
   *.C, *.h, *.hh    --  source for test
   *cdf,INP1*,geqdsk --  sample input files for rests
   *ref              --  comparison output

in sub directory i2mex:
   Makefile          --  Makefile to build i2mex
   *.f90             --  sources for i2mex library 

in sub directory esc:
   Makefile          --  Makefile to build esc
   *.c               --  sources for esc library 

in sub directory generic_dummy:
   Makefile          --  Makefile to build dummy library
   *.f *.f90         --  source for dummy library 


================
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:
./pest3.2         --  sources and Makefile
./esc             --  sources and Makefile
./i2mex           --  sources and Makefile
./share           --  include file Make.flags, Make.local.sample
./generic_dummy   --  sources and Makefile

The Makefile will create more sub directories,

lib:                for the libraries, libxplasma.a, libesc.a and
			libgeneric_dummy.a
obj/pest3.2:        for compiled objects and pre-processed sources
obj/esc:            for compiled objects 
obj/i2mex:          for compiled objects 
obj/:generic_dummy: for compiled objects
test:               for the test program and the sample output files.

By default these directories are created in  
./<PLATFORM>, 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 <PLATFORM> 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:
===================
           libxplasma.a   -> NTCC module XPLASMA
           libpspline.a   -> NTCC module PSPLINE   
           libezcdf.a     -> NTCC module EZcdf (supplied with PSPLINE)
           liblsode.a     -> NTCC module LSODE (supplied with XPLASMA)
           netCDF
	   lapack
	   blas
If you want MDSplus support:
           libtrxplib.a   -> NTCC module TrXplib 
           libtrread.a    -> NTCC module TrRead 
	   MDSplus

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

netCDF, blas, lapack
--------------------
netCDF, lapack and blas 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 share/Make.local.sample
and rename it to share/Make.local.
 
MDSplus
-------
MdsLib is assumed to be in /usr/local/mdslib/lib
if not, define MDSPLUS_DIR or modify share/Make.local
 
xplasma, pspline, ezcdf, trread and trxplib
-------------------------------------------
If your site already has these libraries installed,
specify their location (library and modules) with PREFIX, 

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

At PPPL these libraries are in /usr/ntcc.

Note: If you don't have all required NTCC libraries, you may download
      them  all together into the same root directory. The Makefile will
      build them all in one step.The top Makefile will not rebuild libraries
      that are alredy installed in either LIBROOT or PREFIX, unless it
      detects a newer source.
      If you wish to re-generate an installed library,you need to do:
	 (cd <libnam>; gmake)     -- to build library  
	 (cd <libnam>; gmake all) -- to build library and test program  



Building libraries and proprams
-------------------------------- 

With MDSplus
> gmake            -- to compile library and link test program

> gmake checklibs  -- tells you what the makefile will do
                      (without any action);
                      it sais which libraries it will make and
                      which ones it already found and where.
Without MDSplus 
> gmake NO_TRXPLIB=Y

> 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 "Portland"  "PathScale"  "GCC" "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 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
=============
directory $OBJ/test  -or-  <PLATFORM>/test  will contain:

pest3.2         :  Test driver
INP1_ieee-be    :  CHEASE binary input for big endian
INP1_ieee-le    :  CHEASE binary input for little endian
eqdsk.cdf       :  Jsolver input 
inp1.cdf        :  CHEASE CDF input
geqdsk          :  
pest3.m         :  Matlab script
results_ref     :  reference output


To run tests:
-------------
 Quick test run:
   cd <PLATFORM>/test
   pest3.2 -fgeqdsk -i4 -m4 -n3

 Run tests and compare output:
   cd <PLATFORM>/test
   gmake tests

     If you have matlab:
  matlab
  >> pest3

See README for details.

================
6. INSTALLATION
================
Install the library and man pages with

    gmake install

This installs libpest3_2.a in $PREFIX/lib
By default PREFIX=/usr/ntcc.

If you want things elsewhere, you can overwrite the default with
> gmake install LIBDIR=/xxx MANDIR=/yyy



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

For Documentation see:

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

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


IF YOU HAVE ANY PROBLEMS, PLEASE CONTACT EITHER:

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

