           Installation Notes for NTCC module I2MEX

Prepared by C.Ludescher-Furth cludesche@pppl.gov  12/05/2000

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

  Dec 02, 2000  -- Created 
  Sep 07, 2006  -- Replaced mex2gtc with mex2eqs (preprocessor for ORBIT)
------------------------------------------------------------------------------

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 i2mex.tar.gz
    tar xvf i2mex.tar
  or
    unzip i2mex.zip

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

   README_i2mex      --  description of I2MEX
   INSTALL_i2mex     --  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 i2mex:
   README            --  copy of README_i2mex
   INSTALL           --  copy of INSTALL_i2mex
   Makefile          --  Makefile to build i2mex library and test
   *.f90             --  source for library and test

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:
./i2mex           --  sources and Makefile
./esc             --  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/i2mex:          for compiled objects and pre-processed sources
obj/esc:            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  
./<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:
===================
           libxplasma.a   -> NTCC module XPLASMA
           libpspline.a   -> NTCC module PSPLINE   
           libezcdf.a     -> NTCC module EZcdf (included in PSPLINE)
           liblsode.a     -> NTCC module LSODE (included in XPLASMA)
           netCDF
	   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
------------
netCDF 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, 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"  "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


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-  <MACHINE>/test  will contain:

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

To run test program:
--------------------
   cd <MACHINE>/test
   ./i2mex

To run mex2eqs: retrieve and map equilibrium data for ORBIT
   ./mex2eqs

See README for details.

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

    gmake install

This installs libi2mex.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:

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

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










