
Contents:

	This directory should contain the following files:

		README
		driver.f
		ifspppl_model.tex
		ifspppl_model.f
		ipin_test1995model
		ipout_test1995model
		ipin_test1994model
		ipout_test1994model
		makefile
		stripx.f
		xtverb.f

	These files are as follows:

	README:  This file.  Brief descriptions of the other files,
		and instructions for compiling the module containing the
		IFS/PPPL model and its simple driver.
	ifspppl_model.tex:  LaTeX file, with fortran code embedded inside,
		that describes this implementation of the IFS/PPPL model.
		This file contains all the documentation, notes and
		references related to this implementation, especially the
		references associated with the IFS/PPPL model itself.
		The fortran coding of the module is embedded in this file.
	ifspppl_model.f:  The fortran code from "ifspppl_model.tex", stripped
		out of the LaTeX file.  This file file is intended only for
		use in compiling the code; the documentation, of course,
		is in the LaTeX file "ifspppl_model.tex".  The makefile
		is written so that the make utility will always extract
		a new version of "ifspppl_model.f" from the fortran code
		imbedded in the LaTeX master file.
	driver.f:  A simple driver program for the IFS/PPPL module.
	ipin_test1995model:  Sample input namelist for the implementation
		of the 1995 IFS/PPPL model in the driver program.
		Simply copy this file to "ipin" and run the driver program
		to replicate this sample case.
	ipout_test1995model:  Sample output; this output matches the
		sample input case "ipin_test1995model".
	ipin_test1994model:  Similar to the above, this is a sample input
		namelist for the driver program, testing the implementation
		of the 1994 IFS/PPPL model.  Simply copy this file to "ipin"
		and run the driver program to replicate this sample case.
	ipout_test1994model:  Sample output; this output matches the
		sample input "ipin_test1994model".
	stripx.f:  Utility routine, used by the driver program, which strips
		all annotation and comments out of the input namelist before
		it is read.
	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 "ifspppl_model.tex" and generate the
		fortran file "ifspppl_model.f"
	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 , and SGI/IRIX 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 "xip" program (the latter is constructed from 
		the simple driver and the IFS/PPPL model routine).

Compilation instructions:

	* On IBM/AIX, SUN/Solaris or SGI/Irix 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 "xip".

          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 editting 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) and for CPU=SGI (for the SGI Origin 200).  
          If you add another CPU branch to the makefile, please let us know 
          what works.


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

	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 the LaTeX file "ifspppl_model.tex",
	  using the utility "xtverb".  The LaTeX file goes into "xtverb" in
	  standard input, while standard output is the fortan file.
	  For example:

		xtverb < ifspppl_model.tex > ifspppl_model.f

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

		xlf -c -o stripx.o stripx.f
		xlf -c -o driver.o driver.f
		xlf -c -o ifspppl_model.o ifspppl_model.f

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

		xlf -o xip driver.o ifspppl_model.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 and SUN systems, along with a brief
	description of each.  These comments should make the task of finding
	analogous compiling options on another system easier.

Running intructions:

	"xip" requires only one input file, the namelist "ipin".

	To produce each of the test cases, copy the appropriate sample input
	file (either "ipin_test1994model" or "ipin_test1995model") to
	the file "ipin" and run "xip".

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

	"ipout" is the output file.  At the beginning of this file, the
	input namelist (with annotation) is reproduced.  Then, the program
	produces a substantial amount of diagnostic output, which fills out
	the rest of this file.

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

If you have any problems, please contact either:

	   Aaron Redd, Lehigh University - aredd@plasma.physics.lehigh.edu
	or Arnold Kritz, Lehigh University - kritz@plasma.physics.lehigh.edu
	or Glenn Bateman, Lehigh University - bateman@plasma.physics.lehigh.edu

This implementation of the IFS/PPPL model is based on material provided by:

	   Bill Dorland, UMD - bdorland@kendall.umd.edu
