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