		Kapisn Neoclassical Transport Model

			   Prepared by 

	Jon Kinsey   -- kinsey@gav.gat.com


UNPACKING INSTRUCTIONS

  > gunzip kapisn.tar.gz
  > tar xvf kapisn.tar


INSTRUCTIONS FOR PRINTING DOCUMENTATION:

	Latex file twice to obtain correct cross-references:

  > latex testkapisn.tex
  > latex testkapisn.tex
  > dvips -f testkapisn.dvi > testkapisn.ps


CONTENTS:

	This directory should contain the following files:

		README
		testkapisn.f
		testkapisn.tex
		kapisn.f
		stripx.f
		xtverb.f
		in-1
		out-1
		in-2
		out-2
		in-3
		out-3
		makefile (uses gmake)

	These files are as follows:

	README:  This file.  Brief descriptions of the other files, and
		instructions for compiling the module containing the
		KAPISN neoclassical transport model and its driver.  

	testkapisn.f: A driver program for the KAPISN module with
	    The fortran coding stripped out of the LaTeX file. This file
		reads the namelist from the input file 'in' and produces 
		the output file 'out' which reflects the input variables 
		and prints the neoclassical ion thermal diffusivity.

	testkapisn.tex:  LaTeX file, with fortran code embedded inside,
		that describes this implementation of the KAPISN
		neoclassical transport model. The makefile is written so that 
        the make utility (using gmake) will always extract a new version 
        of "testkapisn.f" from the fortran code embedded in the LaTeX 
        master file.
	
	kapisn.f:  The fortran code for the kapisn KAPISN. 

	stripx.f:  Utility routine, used by the driver program, which
		strips all annotation and comments out of the input
		namelist before it is read.  Modified by D. McCune 
        (November 1998) to work with namelist on the DEC alpha
		workstation.

	xtverb.f:  Utility program which can pull fortran code out of a
		LaTeX document, leaving a fortran file.  In this case,
		it is used to read the tex files described above and
		generate the corresponding fortran file.

	in-1:   Sample input namelist for running the KAPISN module
		using the modified Hazeltine-Hinton model.  Copy this 
        file to a file called "in" before running this module.

	out-1:  Sample output. This file contains the output that
		should be produced in file "out" when the sample
		input "in-1" file is used.
		
	in-2:   Sample input namelist for running the KAPISN module
		using the modified Chang-Hinton model with q < 1.  Copy this 
        file to a file called "in" before running this module.

	out-2:  Sample output. This file contains the output that
		should be produced in file "out" when the sample
		input "in-2" file is used.

	in-3:   Sample input namelist for running the KAPISN module
		using the modified Chang-Hinton model with q > 1.  Copy this 
        file to a file called "in" before running this module.

	out-3:  Sample output. This file contains the output that
		should be produced in file "out" when the sample
		input "in-3" file is used.

	makefile: File used by the gmake utility.  NOTE, "gmake" not
		"make" must be used. This makefile has been written to
		work on the IBM/AIX, SUN/Solaris, SGI/IRIX, DEC/alpha,
		and Linux platforms and can be modified to work on other
		systems.  This makefile contains the instructions for
		compiling and building both the "xtverb" utility and
		the "xkapisn" program.  The choice of the CPU environment 
		variable determines the platform and whether the 
		compilation is single or double precision.  The executable 
		file, "testkapisn" is constructed using the files described 
		above. The makefile also includes a clean option 
		("gmake clean") to remove all binaries.

COMPILATION INSTRUCTIONS:

       * On IBM/AIX, SUN/Solaris, SGI/Irix, DEC/alpha or Linux platforms, 
         simply type:

		gmake

	at the unix prompt.  The makefile contains all the
	instructions needed by the "gmake" utility to create the test
	executable, which is called "testkapisn".

	NOTE: The makefile uses make-variable CPU to control platform-
	dependent settings. CPU can be set either by defining an
	environment variable CPU, or by editing the makefile to
	include a line CPU=... , or by typing CPU=... on the gmake
	execute line.  If CPU is not set, it is defaulted to IBM. This
	version of the makefile is prepared for CPU=IBM (for an
	IBM/AIX system), for CPU=SOL (for Solaris), for CPU=SGI
	(for the SGI Origin 200), CPU=DEC (for the DEC alpha), CPU=NAG
    for Linux systems with the NAG compiler and CPU=PGI for Linux
    systems with the Portland Group compiler. For CPU=PGI, the
    makefile utilizes optimization for the Pentium II processor.
    If you add another CPU branch to the makefile, please let me 
    know what works.


	PRECISION: Note that the makefile CPU environment determines
    flags for the DEC, IBM, SGI, SOL(SUN), and Linux platforms. The module 
    is double precision but can be easily converted to single precision.
	However, it has been tested ONLY as a double precision module.

      * If the make utility does not work, or if the module is being
	compiled on a non-IBM, non-SUN, non SGI, non DEC, or non Linux platform,
	then the compilations will need to be done by hand.  What
	follows are step-by-step instructions for creating the test
	executable "testkapisn".

    I/O numbers: Unit numbers used for input and output are:
    4 for file='temp', 5 for file='in', and 6 for file='out'.

	1) First, generate the utility "xtverb".  The only source code
	   needed is xtverb.f.  For example, on an IBM/AIX system, this
	   compilation could be accomplished by:

		xlf -o xtverb xtverb.f

	2) Pull the fortran code out of each LaTeX file using the
	   utility "xtverb".  The LaTeX file goes into "xtverb" in
	   standard input, while standard output is the fortran file.
	   
		xtverb < kapisn.tex > kapisn.f

	3) Compile and produce object codes for "testkapisn.f" and "kapisn.f".
	   On the IBM/AIX system, an object code is produced when the
	   compiler is invoked with a "-c" option:

		xlf -c -o testkapisn.o testkapisn.f
		xlf -c -o kapisn.o kapisn.f
		xlf -c -o stripx.o stripx.f

	4) Link these object codes together, producing the executable "xkapisn".
	   For example:

		xlf -o xkapisn testkapisn.o kapisn.o stripx.o

	There are, of course, several compiling options that one could
	use when carrying out steps (1)-(4).  The makefile contains
	the recommended compiling options for the IBM, SGI, SUN, and DEC
        systems, along with a brief description of each.  These
	comments should make the task of finding analogous compiling
	options on another system easier.

RUNNING INSTRUCTIONS:

	"xkapisn" requires only one input file, the namelist "in".

	To produce a test case, copy the sample input "in_1", "in_2",
	or "in_3" to the file "in" and run "xkapisn".

	As it runs, "xkapisn" will generate two files: "temp" and "out".
	
	"temp" is a temporary file, containing the input namelist
	without annotation and notes.  "temp" is actually the file
	read during the namelist read in the xkapisn program.

	"out" is the output file.  At the beginning of this file,
	the input namelist (with annotation) is reproduced.  

	When this package is ported to a new platform, it is suggested
	that the test case be run first.  Each time, compare the
	output file "out" with the sample output file, "out_1" in order 
	to verify that all is working as expected.

IF YOU HAVE ANY PROBLEMS, PLEASE CONTACT:

        Jon Kinsey, kinsey@gav.gat.com

