            Porcelli Sawtooth Trigger Module README File

                           Prepared by 

        Glenn Bateman -- bateman@lehigh.edu
        Arnold H. Kritz --- kritz@lehigh.edu
        Canh N. Nguyen

        The Porcelli module implements the sawtooth trigger model
        described in the paper by

        F. Porcelli, D. Boucher and M.N. Rosenbluth
        Plasma Phys. Control. Fusion 38 (1996) 2163-2186.


REVISION HISTORY
----------------
       Date            Description

   29 May 2006         Fortran 90 Module completed and tested


UNPACKING INSTRUCTIONS

  > gunzip porcelli.tar.gz
  > tar xvf porcelli.tar


CONTENTS:

        This directory should contain the following files:

                README
                test_porcelli_module.f90
                porcelli_module.f90
                porcelli_auxiliary
                stripx.f
                s2tex.py
                input_st_not_triggered
                input_st_triggered
                output_st_not_triggered
                output_st_triggered
                makefile

        These files are as follows:

        README:  This file.  Brief descriptions of the other files,
                and instructions for extracting documentation and 
                for compiling the Porcelli module and its 
                driver program test_porcelli_module.f90
                Note that the Porcelli module has been tested using only
                double precision with the precision set by compiler flags.

        test_porcelli_module.f90:
                File containing fortran 90 code and documentation.
                The fortran program in file test_porcelli_module.f90
                reads the input file "input" and writes the output
                file, "output".  Parabolic pressure and magnetic shear
                profiles, and the associated normalized gradients are
                prepared for the call to the porcelli_model subroutine.
                
        porcelli_module.f90:
                File containing fortran 90 code and documentation
                for the Porcelli module.

        porcelli_auxiliary.f:  Auxiliary routines that are used 
                within procelli_module.f90.

        stripx.f:  Utility routine, used by the driver program, which
                strips all annotation and comments out of the input
                namelist before it is read.

        s2tex.py:  Python utility script that converts source code files
                into LaTeX files.  Specially labeled comments in the
                source code file (comment lines that begin with !|
                in the case of Fortran code) are converted into
                text that is typeset using LaTeX.  The rest of the
                source code is placed in sections between 
                \begin{verbatim} and \end{verbatim} in the LaTeX file.
                For using s2tex.py, see the section below on 
                "INSTRUCTIONS FOR PRINTING DOCUMENTATION".

        input_st_triggered:  Sample input namelist for running 
                test_porcelli_module to produce an output in which
                a sawtooth crash is triggered.
                Copy this file to a file called 
                "input" before running test_porcelli_module.

        output_st_triggered: Output file produced by running
                test_porcelli_module.  A sawtooth crash is
                triggered in this example.

        input_st_not_triggered:  Sample input namelist for running 
                test_porcelli_module to produce an output in which
                a sawtooth crash is not triggered.
                Copy this file to a file called 
                "input" before running test_porcelli_module.

        output_st_not_triggered: Output file produced by running
                test_porcelli_module.  A sawtooth crash is
                not triggered in this example.


        makefile: File used by the make or gmake utility.
                This makefile has been written to work on LINUX,
                CYGWIN, IBM/AIX, SUN/Solaris, SGI/IRIX, HP/UX, and
                DEC platforms and can be modified to work on other
                systems.  This makefile contains the instructions for
                compiling and building the "test_porcelli_module" program.
                The executable file, "test_porcelli_module"
                is constructed using the files described above.


INSTRUCTIONS FOR PRINTING DOCUMENTATION:

    LaTeX files can be produced from two of the source files
by typing:

  > python s2tex.py porcelli_module.f90
  > python s2tex.py test_porcelli_module.f90

    The resulting LaTeX files can be turned into PostScript files
by typing:  (Note: apply latex to these files twice to obtain correct 
cross-references.)

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

with the same procedure applied to test_porcelli_module.tex.

Note that s2tex.py also produces the files:
porcelli_module.pure.tex in which the source code is stripped out and
porcelli_module.pure.f90 in which the LaTeX text is stripped out.


COMPILATION INSTRUCTIONS:

       * First, set the environmental variable "CPU" to one of the following:

G95      for the g95 compiler on LINUX or CYGWIN systems
FUJITSU  for the Lahey/Fujitsu F90/95 compiler on LINUX systems
IBM      for the standard compiler on IBM/AIX workstations
SOL      for the standard compiler on Sun Solaris workstations
SGI      for the standard compiler on SGI Origin 200 workstations
DEC      for the standard compiler on DEC alpha workstations
HP       for the standard compiler on Hewlett Packard workstations

       For example, in the Bourne or K shell on an SGI workstation, type:

export CPU=SGI

       If you are using the C-shell on an SGI workstation, type

setenv CPU SGI

       * To compile the stand-alone test code "test_porcelli_module"
         simply type:

                make  (or "gmake")

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

        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 or make
        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), for CPU=DEC (for the DEC), and for
        CPU=HP (for the Hewlett Packard), for the Lahey/Fujitsu
        F90/95 compiler set CPU=FUJITSU, and for the G95 compiler
        set CPU=G95.  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, non-SGI, non-DEC, or 
        non-HP platform then the compilations will need to be done by 
        hand. What follows are step-by-step instructions for creating 
        the test executable test_porcelli_module.

        1) Compile and produce object codes for "test_porcelli_module.f90",
           "porcelli_module.f90", "porcelli_auxiliary.f" and "stripx.f". 
           Suppose the Fortran 90 compiler on your system is called
           "f90".  Suppose "-r8" is the option needed to promote all
           single precision variables to double precision.  
           An object code is produced when
           the compiler is invoked with a "-c" option:

                f90 -c -r8 -o porcelli_module.o porcelli_module.f90
                f90 -c -r8 -o test_porcelli_module.o test_porcelli_module.f90
                f90 -c -r8 -o porcelli_auxiliary.o porcelli_auxiliary.f
                f90 -c -r8 -o stripx.o stripx.f

           Note that the file porcelli_module.f90 must be compiled before
           compiling the file test_porcelli_module.f90, since some data 
           modules contained in porcelli_module.f90 are used in
           test_porcelli_module.f90.

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

                f90 -r8 -o test_porcelli_module \
                test_porcelli_module.o porcelli_module.o \
                porcelli_auxiliary.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:

        "test_porcelli_module" requires only one input file,
        the namelist "input".

        To produce each of the test cases, copy the sample input
        file such as  "input_st_triggered", to the file "input"
        and run "test_porcelli_module".

        As it runs, "test_porcelli_module" will generate two files:
        "temp" and "output".
        
        "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 test_porcelli_module program.

        "output" 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 "output" to the appropriate sample output file, in
        order to verify that all is working as expected.  For machines
        other than HP and IBM, use the SGI version sample output files
        for comparison.

USAGE NOTES:

        The Porcelli module implements the sawtooth trigger model
        described in the paper by

        F. Porcelli, D. Boucher and M.N. Rosenbluth
        Plasma Phys. Control. Fusion 38 (1996) 2163-2186.

        The Porcelli module is intended to be used within integrated
        modeling codes.  It must be coupled together with a module
        that implements the changes in plasma profiles produced by
        a sawtooth crash.  It is recommended that Porcelli's 
        prescription for partial magnetic reconnection in an anular
        region be used in the sawtooth crash module.

        Note that the minor radius of the q = 1 surface (rminor_q_1)
        must be computed before calling the Porocelli module.
        
        This module has been tested and used only with double precision.

IF YOU HAVE ANY PROBLEMS, PLEASE CONTACT EITHER:


        GLENN BATEMAN, Lehigh University 
                 bateman@lehigh.edu

        or

        ARNOLD KRITZ, Lehigh University 
                 kritz@lehigh.edu


This implementation of the PORCELLI sawtooth model is based on work
carried out by:

Glenn Bateman, Lehigh University
Canh N. Nguyen
Arnold H. Kritz, Lehigh University
