$Id: README,v 1.2 2007/07/23 16:00:57 meyer Exp $

To build and test the teq module, simply type:

./configure --with-SEPLIBPATH=/path/to/separatrix/library && make && make test

"configure" generates a Makefile for your system.

"make" builds the teq library libteq.a.

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

Some older versions of the make utility might not work. Then try gmake instead
(the GNU implementation of make).

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

./configure --with-SEPLIBPATH=/path/to/separatrix/library \
--with-LAPACKFLAGS="-L$HOME/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 teq (the source directory) and want to build the
library in a subdirectory called build, just do the following:

mkdir build && cd build && ../configure \
--with-SEPLIBPATH=/path/to/separatrix/library && make

When you type "make test", a demonstration driver is compiled and executed.
The source code, driver.f90, demonstrates the basic use of the teq library and
should be fairly self-explanatory. Direct (free-boundary) equilibria can either
be loaded from a Corsica save file (*.in) or calculated from scratch (by doing
a dead start). In the demo driver the direct equilibria are perturbed and then
recalculated to demonstrate the convergence of the Grad-Shafranov solver.
When a direct equilibrium has been found, the inverse equilibrium can be
calculated. The direct and inverse equilibria are finally stored in the file
driver.sav (in Corsica save file format).

The input variables are described in the file teqinit.f90. Also, the upper
level variable are desribed in teqlib.f90

To use exception handling (currently only supported on Linux), see
the file SeparatrixManual.pdf that comes with the separatrix module.

The IDL script teqplot.pro can be used to plot the equilibria. In the
teq directory type:

idl
  .run teqplot
  teqplot, 'input/foo.in'
  exit

Here foo.in is the desired savefile and driver.eps is the resultant
postscript file. 

The teq library is built with the same floating-point precision as the
separatrix library (8-byte floating point by default). To switch to 4-byte
floating point, change line 7 in the file separatrix/utils.f90 from "rq=r8" to
"rq=r4" and rebuild first the separatrix library and then the teq library.

To get help, send an email to <teq-users@fusion.txcorp.com>.

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

Fedora Core 3:
 Lahey/Fujitsu lf95 6.2

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:

Intel ifort 8.0 is known to ICE (Internal Compiler Error) on gradsh.f90,
line 113, even without optimization. However, at least one user reports that
ifort 8.0 did manage to build the teq library.

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

On Darwin, xlf -O2 gives incorrect output, xlf -O0 works OK.

On HP-UX:
* f90 -O2 gives incorrect output, f90 -O1 works OK.
* you have to comment out the call to time_date in teqlib.f90 or you'll
  get a bus error.
