README_GTNEUT.txt

This is the README file for the distribution of the Transmission and Escape 
Probability (TEP) Neutral Transport Code GTNEUT.

Prepared by John Mandrekas -- john.mandrekas@me.gatech.edu
4/24/2004 : minor update
9/15/2004 : NTCC version

CONTACT INFORMATION:
--------------------
Dr. John Mandrekas
Georgia Institute of Technology
Fusion Research Center
900 Atlantic Drive
Atlanta, GA 30332-0425, USA

Tel: (404) 894-7730
FAX: (404) 894-3733

CONTENTS OF COMPRESSED TAR ARCHIVE:
-----------------------------------

The following files are included in the compressed tar file gtneut2003.tar.gz:


README_GTNEUT.txt : This file
GTNEUTPaper2004.pdf : A copy of a recent paper describing GTNEUT and published in 
Comput. Phys. Commun. 161 (2004) 36.

The following Fortran source files and include files:

main.f
bickley.f
calcRect.f
calcmfp.f
calcrefln.f
calcrparms.f
calctransm.f
calcxswms.f
checkinp.f
degasread.f
escape.f
ndata.f
output.f
pbalance.f
postsolver.f
qgauss.f
rectinp.f
reflect.f
setup.f
simpson.f
solverf.f
solvers.f
svdegas.f
svefj.f
svjanev.f
tij.f
transmcoeff.f
wmsdata.f
zstop.f

dummy_umf.f

consts.inc
comiou.inc
wmsdata.inc
neutGlob.inc
locGeom.inc
degdat.inc

Makefile :

A generic makefile which should be customized by potential users for their 
computing platform. The version included in this distribution is for a SUN 
Solaris 9 system with the Forte Developer 7 Fortran 95 compiler tools. 
The code has been tested succesfully on HP systems running HP-UX 11i with the
2.6.4 version of the f90 compiler, on Intel Pentium systems running Linux 
(RedHat 8 and 9) and the Intel fortran compiler (versions 7 and 8) and on
Intel Pentium systems running Windows (XP, NT, 9x) and the Absoft Fortran
compiler, version 7.5. The code is written in standard Fortran 77 with no
vendor-specific extensions (with the exception of the widely supported use
of INCLUDE and NAMELIST statements) and should compile on all platforms 
using standard compiler flags.


Atomic Data files:
-----------------
ehr1.dat
cxionh.dat 

Input and Output files for the test problems:
---------------------------------------------

toneut5x4     : Input file for the first test case (5x4 rectangular geometry
                model problem)
neut5x4.out   : Output for the first test case
neut5x4.dbg   : Debugging output for the first test case

toneutDIIID   : Input file for the second test case (DIII-D test problem)
neutDIIID.out : Output file for the second test case


STEPS TO BUILD AND TEST THE CODE:
---------------------------------

Step 1: Unpack the distribution

The following two commands uncompress and unpack the distribution file 
gtneut2003.tar.gz in a (preferably empty) directory, extracting all the 
files listed above:

   > gunzip gtneut2004.tar.gz
   > tar xvf gtneut2004.tar

If using the ZIP archive, then type:
   > unzip gtneut2004.zip

Step 2: Building the code

After the user edits the supplied Makefile to customize it for his or her 
environment (which usually involves editing the FC, LD, FFLAGS, LDFLAGS 
environment variables and making sure the LIBS variable points to the right 
location for the LAPACK and, if available, the UMFPACK libraries), typing 
"make" should produce the GTNEUT executable "xneut". (See important note 
below regarding the choice of the linear system solver.)

Step 3: Testing the code

Typing

> ./xneut 

in the current directory (where the executable xneut is located), runs the 
GTNEUT code. The code expects to find the input file "toneut" in the current 
directory. Therefore, to run test case 1, first copy the input file toneut5x4
into toneut (e.g., 'cp toneut5x4 toneut') and similarly for the second test 
case. Upon successful completion, some output information is written to the 
screen (unit 6 in most systems) and the normal and debug output files 
'neut.out' and 'neut.dbg' are created. These files should then be compared 
to the sample output files included in the distribution.

IMPORTANT NOTE REGARDING LINEAR SYSTEM SOLVERS:
---------------------------------------------- 
As discussed in the manuscript (Section 3.2), GTNEUT performs best when it is
linked with the sparse linear system solver library UMFPACK. This package can
be obtained from http://www.cise.ufl.edu/research/sparse/umfpack/old.html (we
have been using version 2.2.1 which is the last Fortran version). Please, read
the UMFPACK License information before obtaining and installing the library.

However, if the user does not have or wish to install the UMFPACK library, 
both test problems can be run with the non-sparse LAPACK linear system solver
DGESV. The LAPACK library can be obtained from netlib.org, although it is 
better to use the optimized versions that are usually included in the software
distribution environment of many UNIX and Fortran compiler vendors. 

If the user decides to use the LAPACK solver, then the following steps should 
be taken:

a) Edit the Makefile to add the supplied dummy_umf.f routine in the SRC field,
   so that the compiler will not complain about unresolved externals.
b) Remove the reference to the UMFPACK library  -L/usr/local/lib -lumfpack 
   from the definition of the LIBS environment variable.
c) Make sure that in both input files the input variable i_solver is equal 
   to 0.

To facilitate the NTCC review process of the code, we have increased the size 
of the PARAMETER constant mxdim in the routine solverf (file solverf.f) from 
its usual value of 400 to 2680, so that the DIII-D test problem can be run, even 
with the LAPACK solver. This has been working well on our SUN workstation 
with 512 MB of memory. If this causes any problems on other platforms or if 
the user has installed the UMFPACK library (or any other sparse linear matrix 
solver, as described in Section 3.2 of the paper) then the value of mxdim 
should be reduced to 400.

END of README_GTNEUT.txt file
