   ISLAND --- Saturated Noeclassical Tearing Mode Island Widths Module

The ISLAND module is used to compute magnetic island widths driven 
by saturated neoclassical tearing modes in tokamak plasmas using the
quasi-linear model published in Phys. Plasmas 11 (2003) 3460--3471.
Multiple magnetic islands interact with one another by means of the
local flattening of the current density profile that is produced by 
each island, as well as interacting by harmonic mixing.  The islands
are treated as a three-dimensional perturbation of an axisymmetric
scalar-pressure MHD equilibrium.  The ISLAND module is intended to 
be used within integrated modeling codes to compute the effects of
a small number (two or three) low-order magnetic islands.

Publications resulting from simulations using the ISLAND module include:

"The ISLAND module for computing magnetic island widths in tokamaks," 
J. Plasma Physics 72 (2006) 1153-1157, 
by F.D. Halpern, G. Bateman, A.H. Kritz and A.Y. Pankin.

"Integrated Simulations of Saturated Neoclassical Tearing Modes in DIII-D, 
Joint European Torus and ITER," Phys. Plasmas 13 (2006) 062510 
by Federico D. Halpern, Glenn Bateman and Arnold H. Kritz.

"Simulation of saturated tearing modes in tokamaks," 
Phys. Plasmas 11, 3460-3471 (2004) 
by Canh N. Nguyen, Glenn Bateman and Arnold H. Kritz.

"Model for Saturated Tearing Modes in Toroidal Geometry," 
Phys. Fluids, 29, 753-761 (1986), by G. Bateman and R.N. Morris.

                      Prepared by 
        Glenn Bateman    -- bateman@lehigh.edu
        Arnold Kritz     -- kritz@lehigh.edu
	Federico Halpern -- feh2@lehigh.edu


REVISION HISTORY
----------------
       date            Description

   3 December 2004    Completed version for NTCC Module Library
  16 December 2005    Updated version for NTCC Module Library

UNPACKING INSTRUCTIONS

  > gunzip island.tar.gz
  > tar xvf island.tar

INSTRUCTIONS FOR PRINTING DOCUMENTATION:

	LaTeX documentation is imbedded in specially marked comments
	lines in the island.f file.  The Python script, s2tex.py,
	can be used to extract the LaTeX file "island.tex" from
	the source file "island.f" by typing the following:

  > python ./s2tex.py island.f

	The LaTeX file "island.tex" can be turned into a PostScript file 
	by typing: 

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

	(Note that "latex" was called twice to resolve cross-references.)

CONTENTS:

        This directory should contain the following files:

                README
		islmod.f
		island.f
		test_island.f

		blas_routines.f
		dode.f
		islmathlib.f
		lapack_routines_1.f
		lapack_routines_2.f
		lsode.f
		zero_finder.f

		makefile
		s2tex.py

                input
                output
		input_DIIID
		output_DIIID
		input_JET
		output_JET

	Call tree: test_island program calls the following routines

	island.f		- ISLAND module
	| zero_finder.f		- non-linear equation zero finder hybrd
	| islmathlib.f		- sorting and interpolation routines

	| lapack_routines_1.f	- LAPACK linear algebra routines
	| lapack_routines_2.f	- LAPACK linear algebra routines
	| | blas_routines.f	- BLAS linear algebra routines
	| lsode.f		- LSODE ODE solver
	| dode.f		- Shampine and Gordon ODE solver



        These files are as follows:

        README:  This file contains brief descriptions of the other files,
                and instructions for compiling the module.  Note, the
                ISLAND module has been tested using double precision,
                with the precision set by compiler flags.

	test_island.f: Source file for the test driver program.

	islmod.f: Source file for the data module used in the ISLAND routines

	island.f: Source file for the ISLAND module.

	blas_routines.f  Source file for the BLAS linear algebra 
		routines used within the ISLAND module

	islmathlib.f:  Source code for routines concerning sorting,
		cubic spline interpolation, Fourier analysys,
		LU decomposition, 
		and Quasi-Hermite piecewise cubic interpolation

	lapack_routines_1.f:  Source code for LAPACK linear algebra routines

	lapack_routines_2.f:  Source code for LAPACK linear algebra routines
		These routines were kept separate because they would
		conflict with routines in our integrated modeling code.

	makefile:  makefile used by gmake

	lsode.f:  Source code for LSODE ODE solver

	dode.f:  Source code for Shampine and Gordon ODE solver
		There is an option in the code to use either one of these
		ODE solvers.

	input:  Sample input file (same as input_DIIID)

	output: Sample output file 

	input_DIIID: Sample input file to compute two islands (3/2 and 2/1)
		in DIII-D geometry.  Copy this file to "input"
		to run the test_island code with this input data.

	output_DIIID:  Output file that was produced on a LINUX
                32 bit computer using the Lahey/Fujitsu F90/95 compiler
		when using "input_DIIID" as the input file for test_island

	input_JET: Sample input file to compute two islands (3/2 and 2/1)
		in JET geometry.  Copy this file to "input"
		to run the test_island code with this input data.

	output_JET:  Output file that was produced on a LINUX
                32 bit computer using the Lahey/Fujitsu F90/95 compiler
		when using "input_DIIID" as the input file for test_island

        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, HP/UX, and
                LINUX platforms. It can be modified to work on other
                systems.  This makefile contains the instructions for
                compiling and building the "xbdped" program.
                The executable file, "xbdped"
                is constructed using the files described above.

NOTE: This ISLAND module has been tested and used only with double 
      precision.


COMPILATION INSTRUCTIONS:

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

INTEL	 for the Intel Fortran Compiler on LINUX systems
G95	 for the g95 Compiler on LINUX/Windows/Cygwin systems
FUJITSU  for the Lahey/Fujitsu F90/95 compiler on LINUX systems (default)
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
HP       for the standard compiler on Hewlett Packard workstations

       For example, in the Bourne shell, to use a FUJITSU compiler, type:

export CPU=FUJITSU

       If you are using the C-shell, to use a FUJITSU compiler, type:

setenv CPU FUJITSU

       * To compile the stand-alone test code "xbdped"
         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 "xbdped".

        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), for CPU=SGI
        (for the SGI Origin 200), and for
        CPU=HP (for the Hewlett Packard), and for the Lahey/Fujitsu
        F90/95 compiler set CPU=FUJITSU.  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, 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 xbdped.

        1) First, compile and produce object codes for "island.f".
	(Note that island.f contains a module needed by test_island.f.)
	Then compile and produce object codes for "blas_routines.f",
	"dode.f", "islmathlib.f", "lapack_routines_1.f",
	"lapack_routines_2.f", "lsode.f", and "zero_finder.f".
	Finally, compile and load "test_island.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 islmod.f
	f90 -c -r8 -o islmod.o island.f
	f90 -c -r8 -o blas_routines.f
	f90 -c -r8 -o dode.f
	f90 -c -r8 -o islmathlib.f
	f90 -c -r8 -o lapack_routines_1.f
	f90 -c -r8 -o lapack_routines_2.f
	f90 -c -r8 -o lsode.f
	f90 -c -r8 -o zero_finder.f
	f90 -c -r8 -o test_island.f


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

                f90 -r8 -o test_island test_island.o islmod.o island.o \
                dode.o islmathlib.o lapack_routines_1.o lapack_routines_2.o \
		lapack_routines_1.o lapack_routines_2.o \
		lsode.o zero_finder.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_island" requires only one input file, the namelist "input".

        To produce each of the test cases, copy the sample input
        file such as "input_DIIID" or "input_JET" to the file "input"
        and run the executable "test_island".

        As it runs, "test_island" 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 xbdped 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.

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 neoclassical tearing mode island module 
is based on work carried out by:

Glenn Bateman, Lehigh University
Arnold H. Kritz, Lehigh University
Federico Halpern, Lehigh University
