           Installation Notes for JSOLVER

Prepared by C.Ludescher-Furth -- cludesche@pppl.gov  05/02/99
Updated by Alex Pletzer 09/24/99

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

  May 05, 1999  -- Created 

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

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

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

or, for zip archives:
  > unzip jsolver.zip


************
2. CONTENTS:
************

INSTALL_Jsolver: This file. Brief descriptions of the other files, and
                 instructions for compiling libjsolver.a and test programs. 

README_Jsolver:  Description of JSOLVER. 

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 invoke Makefiles in all subdirectories.

-- in subdirectory jsolver:

   INSTALL:         This file. A copy of INSTALL_Jsolver from above.
   README:          Description of JSOLVER. A copy of README_Jsolver
                    from above. 
   Makefile:        to build libjsolver.a, test program and utilities.

   Sources to build libjsolver.a:
        *.f90, *.h, *.c

   Sources for programs:
        drive.f90   tsc2cdf.f90   tsclong2cdf.f90

   Sample input/output files:
       inequ.ref jso.profiles.ref  jso.scalars.ref eqdsa.cdf 

-- 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 portlib:
   Sources to build internally used library libportlib.a:
   *.F. *.f9f, *.c, *.h

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


****************
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:
./jsolver          --  Sources, test data and Makefile
./share            --  Make include files
./portlib          --  Sources and Makefile
./include/fpreproc --  *.h files for cpp

The makefile will create the following sub directories,
lib:          for the library, libjsolver.a
mod:          for the f90 modules
test:         for the programs and the sample in/output.
obj/<libnam>: for preprocessed sources and objects

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
      $HOME/foo/LINUX/{lib,mod,obj,test}.


You can overwrite the destination by defining OBJ, as an environment
variable (e.g. in your login setup, export OBJ=/dir1/dir2),
or with make (e.g. "gmake 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,test,mod,obj}.

The rational 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=.
      Alternatively you can modify share/Make.local.sample
      and rename it to share/Make.local.


*************************
4. BUILDING INSTRUCTIONS:
************************* 

Required Compilers:
===================
       gcc        -- for pre-processing (exept on CRAY)
       Fortran 90
       C

Required Libraries:
===================
       libpspline.a   -> NTCC module PSPLINE   
       libezcdf.a     -> NTCC module EZcdf (included in PSPLINE)
       lapack
       blas
       netCDF

Required Fortran90 Modules:
===========================
           ezcdf_*   : used by reqdsk and weqdsk soubroutines 

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

lapack, blas and netCDF
-----------------------
lapack, blas and netCDF are assumed to be in /usr/local,
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.


pspline and ezcdf
-----------------
If your site already has pspline and ezcdf libraries installed,
specify their location (library and modules) with PREFIX, 

e.g. "gmake PREFIX=/my_lib"

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 libjsolver and proprams
--------------------------------
> gmake             -- to build/link library and programs

> 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.
 
> gmake clean       -- to remove all .o files
> gmake realclean   -- to remove everything but sources.

> 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"  "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 f90: 
> gmake NAG90=y

To use vastf90:
> gmake VAST90=y

Caveat: Be careful to use the same compiler for all objects.


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

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

jsolver     :  Test driver for JSOLVER
eqdsa.cdf   :  optional sample input from TSC (converted)
inequ.ref   :  reference

tsc2cdf     : to convert binary output from TSC to netCDF
tsclong2cdf : same for INTEGER*8

To run test:
cd <MACHINE>/test
./jsolver

For details see README or http://w3.pppl.gov/NTCC/Jsolver


**********************
6. FINAL INSTALLATION:
**********************

Choose or create the root directory in which you wish to install the software.
A common locations 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.
There is "no default" for PREFIX.

The assumptions are:

libraries in:   $PREFIX/lib        = $LIBDIR       
f90 modules in: $PREFIX/mod        = $MODDIR       
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 PREFIX=/dir1/dir2/
    to install into /dir1/dir2/...

> gmake install
    if you are using share/Make.local


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

NOTE:
-----
The library is installed as libjsolver.a
Users should link with

-L<PREFIX>/lib -ljsolver

Make sure users know what <PREFIX> is.

See 4. BUILDING INSTRUCTIONS about other required libraries.

tsc2cdf and tsclong2cdf
-----------------------
These programs are not installed.
If you want to keep them, copy them into an appropriate location:
cp <machine>/test/tsc2cdf <target>/bin/ 
cp <machine>/test/tsclong2cdf <target>/bin/ 


After you have installed the software, you can delete the entire tree
with
> cd ..
> rm -r foo
   assuming the previous example.


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

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

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


