$Id: README,v 1.1.2.9 2006/04/17 23:42:56 carlsson Exp $

To build and test the separatrix module, simply type:

./configure && make && make test

"configure" generates a Makefile for your system.

"make" builds the separatrix library libseparatrix.a.

"make test" builds and executes a demonstration driver program.

You might have to specify where the lapack library is installed. For example:

./configure --with-LAPACKFLAGS="-L../LAPACK -llapack -lblas"

The configure script should be able to find a working F90 compiler (if one is
available on your system of course). However, if more than one F90 compiler is
available, you might want to override the configure script. For example, if you
have both pgf90 and lf95 installed on a Linux box, the configure script will
choose lf95. To override this you can either

./configure --with-F90=pgf90

or set the shell variable F90 to "pgf90".

You don't have to build the code in the source directory. For example, if you
are in the directory separatrix (the source directory) and want to build the
library in a subdirectory called build, just do the following:

mkdir build && cd build && ../configure && make

When you type "make test", a demonstration driver is compiled and executed.
The driver loads four equilibria (DIII-D, SSPX, FIRE and ITER) and calls the
separatrix library to find the separatrices. The output in ASCII format is
dumped in the *.out files. If you have RSI IDL installed you can run the script
sep.pro to plot the output. The driver also makes a simple test of the validity
of the output by testing that the endpoints of the separatrices are within
0.001 cm of known good values. The output should look something like (the exact
values are compiler dependent):

 1 gd3df
  Error is within tolerance: 1.122254637821255E-06 cm < 1.0e-3 cm
 2 gsspx
  Error is within tolerance: 1.137602293791307E-06 cm < 1.0e-3 cm
 3 gfire
  Error is within tolerance: 6.546844133481500E-08 cm < 1.0e-3 cm
 4 giter
  Error is within tolerance: 9.261018085628088E-07 cm < 1.0e-3 cm

A warning message will be printed if the output is incorrect.

Look in the user manual (SeparatrixManual.pdf) for information about how to use
the separatrix library.

By default the separatrix library is built for 8-byte floating point.
To switch to 4-byte floating point, change line 7 in the file utils.f90
from "rq=r8" to "rq=r4" and rebuild the library.

Exception handling has been added to the separatrix library (see the user
manual for details). The purpose is to return control to the driver if
something goes wrong inside the separatrix library. Exception handling
currently only works on Linux with either lf95, ifort or pgf90. On unsupported
platforms a warning message is printed when the driver attempts to enable the
exception handling by calling the function catch_xcpt() ["WARNING! Fortran
exception handling is not enabled!"].

To get help, send an email to <teq-users@fusion.txcorp.com>
(the separatrix module shares the mailing list of the teq module).

The separatrix module has been built and tested with the following
OS/compiler combinations (current as of 03/02/06):

Fedora Core 3:
 Lahey/Fujitsu lf95 6.2
 Intel ifort 8.0

Redhat7.2:
 Portland Group pgf90 6.0

Darwin (Mac OS X) 7.9.0:
 IBM xlf 8.1

HP-UX 11.11:
 HP f90 2.8

Known problems:

Redhat bumped up the stack size from 8MB to 10MB for Enterprise Linux
release 3, causing lf95 to break. A fix for the problem is presented at:
<http://www.laheyforum.com/archive/index.php/t-10322>.
