                             Paleoclassical Transport Model
   Prepared by

   Lixiang Luo (lixiang.luo@lehigh.edu)
   Tariq Rafiq (rafiq@lehigh.edu)
   Glenn Bateman (bateman@lehigh.edu)
   Arnold Kritz (kritz@lehigh.edu)

-------------------------
REVISION HISTORY
-------------------------

   +-----------------------------------+
   |Date       |Description            |
   |-----------+-----------------------|
   |6-May-2011 |Initial release        |
   +-----------------------------------+


-------------------------
INTRODUCTION
-------------------------

  MODPALEO module contains the "PALEO" subroutine which calculates the electron
  thermal transport according to the Paleoclassical transport model.
  Paleoclassical transport model is derived by J.D Callen [J.D. Callen, Nucl.
  Fusion 45, 1120 (2005)]. It has been hypothesized that part of the radial
  electron heat transport in current-carrying, magnetically confined, toroidal
  plasmas results from paleoclassical Coulomb collision processes. These
  processes involve parallel electron heat conduction and magnetic field
  diffusion. In this model, the electron temperature equilibrates along magnetic
  field lines while diffusing field lines carry this equilibrated electron
  temperature with them, which results in a radial electron heat diffusivity.
  The inputs of the subroutine include the parallel neoclassical resistivity,
  which can be calculated by external codes such as NCLASS (Houlberg, Phys.
  Plasmas, 1997). The equations used in this module can be found in the
  paper [T. Rafiq et. al., Phys. Plasmas, 16, 032505, 2009].


-------------------------
PREREQUISITES
-------------------------

   MODPALEO is intended to be built on an x86 POSIX-complaint OS (UNIX, Linux,
   Cygwin, etc.) with a Fortran 90 compiler. The rest of README will assume that
   you are running an x86 Linux system with a BASH shell. The GNU version of
   "make" tool and must be installed in the OS. Building on Cygwin is supported,
   although the compiler options are much more limited. Building on other
   architectures may be possible but not yet tested. Users and developers are
   welcome to send in their experience on building MODPALEO on different
   architectures.


-------------------------
CONTENTS
-------------------------

   First, unpack the source using this command on any POSIX-compliant
   operating system:

 $ tar xvzf modpaleo.tar.gz

   Upon unpacking, you will be able to see the following files, organized in
   a cascade structure:


      modpaleo/
         | Makefile
         | README
         | modpaleo.f90
         | testpaleo.f90
         |
         +- case1/
         |   | sample_input
         |   | sample_output
         |
         +- case2/
         |   | sample_input
         |   | sample_output
         |
         +- case3/
             | sample_input
             | sample_output


   These files are as follows:

   Makefile        Makefile for building the binary files.

   README          This file. Brief descriptions of the other files, and
                   instructions for installing MODPALEO in other programs.

   modpaleo.f90    The F90 source file containing the paleo subroutine
                   for paleoclassical thermal transport.

   testpaleo.f90   The F90 source file of the driver program. The program
                   reads the input file "input" and writes the output
                   file, "output".

   case1           Sample input data generated from a D3D-like L-mode
                   discharge with flat density profile.

   case2           Sample input data generated from a D3D-like L-mode
                   discharge with peaked density profile.

   case3           Sample input data generated from a D3D-like H-mode
                   discharge.

   Inside each case subdirectory:

   sample_input    Sample input files.
   sample_output   Sample output files.


-------------------------
COMPILATION INSTRUCTIONS
-------------------------

   Follow the two-step procedure to build the codes:

    1. Set the environmental variable "MMMFC" to the compiler command on
       your system. It is compatible with the compiler settings of MMM7.1.
       Here are some common examples:

       +-----------------------------------------------+
       |If you are using ...|MMMFC should be set to ...|
       |--------------------+--------------------------|
       |G95                 |g95                       |
       |--------------------+--------------------------|
       |GNU Fortran         |gfortran                  |
       |--------------------+--------------------------|
       |Intel Fortran       |ifort                     |
       |--------------------+--------------------------|
       |PathScale Fortran   |pathf95                   |
       +-----------------------------------------------+

       Use "export" on Bourne-style shells and "setenv" on C-style shells
       to set environment variables. For example, on BASH:

          $ export MMMFC=pathf95

       or on TCSH:

          % setenv MMMFC pathf95

       Note that if you do not set any value for MMMFC, it will default to
       gfortran.

    2. To compile the whole package simply run:

          $ make

       inside the main directory to the master makefile. The binary files
       (*.o and testpaleo) are placed alongside with their source codes.
       To delete all binary files, use:

          $ make clean

       You can generate debugging-ready binary files using these commands:

          $ make clean
          $ make debug


-------------------------
TESTING INSTRUCTIONS
-------------------------

   The driver program "testpaleo" requires only one input file called
   "input". Since the input file is a Fortran namelist file, the variables
   can be arranged in any order.

   To produce the test cases:

    1. Change the current directory to case1 (or case2, case3, etc.)
    2. Copy the sample input file, "sample_input", to "input":

          $ cp sample_input input

    3. Run the driver program by

          $ ../testpaleo

       Note that the driver program is located in the parent directory.

   As it runs, "testpaleo" will generate an output file "output". The output
   file contains a listing of input arguments for subroutine paleo and it is
   followed by a listing of all output arguments of the subroutine. You can then
   do a simple comparison between the output and the given sample, using the
   "diff" command:

       $ diff output sample_output

   which should give little to no output, if the driver program is
   correctly built.


-------------------------
LINKING INSTRUCTIONS
-------------------------

   To use MODPALEO in your own program, the following issues need to be
   taken care of:

    1. The "USE" statement in your Fortran 90 program,
    2. A proper "CALL" statement of the paleo subroutine,
    3. Linking of modpaleo.o against other binary object files.

   The compilation of any source file that use the modpaleo module requires
   the compiler to correctly locate the module file ("modpaleo.mod"). Most
   compiler search "*.mod" files in directories listed after the -I option.
   Module files are generally incompatible among different compilers. You
   will not be able to compile the driver program with compiler B if the
   MODPALEO module is compiled using compiler A.

   Linking of "modpaleo.o" against other binary object files should only
   involve putting modpaleo.o in the object file list, as long as the file
   can be located by the compiler. Please follow the instructions of your
   Fortran compiler to set appropriate options.


-------------------------
COMPILER-WISE NOTES
-------------------------

  g95

   Earlier versions may have problems with data types. Please use the latest
   stable version (>0.93).


  PathScale (as for v3.2)

   The driver program generated by this compiler cannot process namelist
   input files with Windows/DOS-style newline. A typical error message when
   running "testpaleo" would look like this:

      lib-4324 : UNRECOVERABLE library error

      ' is unrecognized in namelist input.
      Encountered during a namelist READ from unit ...

   A tool called "dos2unix" (included in Cygwin and most Linux distributions)
   can be used to convert these input files.


-------------------------
CONTACTS
-------------------------

If you have any problems, please contact

Lixiang Luo
      Department of Physics, Lehigh University
      lixiang.luo@lehigh.edu

Tariq Rafiq
      Department of Physics, Lehigh University
      rafiq@lehigh.edu

Arnold H. Kritz
      Department of Physics, Lehigh University
      kritz@lehigh.edu
