NUT0.1 - A fast 3-D neutral transport subroutine:

Prashant M. Valanju                          Last Update Aug 21 2003
email contact: pvalanju@mail.utexas.edu
Phone: 512-471-1350
NUT0 Website: http://www.frc.utexas.edu/pv/Nut0Manual/index.html
Thanks to: James C. Wiley and John Mandrekas.

 This README file just gets you started.
 Please read the more elaborate PDF manual for more details
 Both came with your .tar file and are also on the web.

QUICK WORD ABOUT NUT: 
---------------------
  NUT is a very fast, semi-analytic algorithm 
  for 3-D neutral transport in 3-D plasma. 
  Analytic integration over short scales yields very high speed, 
  as compared to Monte-Carlo methods, 
  without compromising accuracy or requiring symmetries.
  A typical 3-d tokamak neutral simulation (TEXT or TFTR) takes < 1 sec on a PC.

QUICK START FOR BEGINNERS: 
--------------------------
Distribution: 
   NUT-0 is downloaded as a single tar file nut0.tar from the NTCC archive. 
   You can email pvalanju@mail.utexas.edu for a copy and help.

1 Download Nut0.tar from NTCC modules on
  webpage http://w3.pppl.gov/rib/repositories/NTCC/catalog/Asset/nut.html,
2 Download nut0.tar from NTCC modules on
  webpage http://w3.pppl.gov/rib/repositories/NTCC/catalog/Asset/nut.html,
3 Type: tar xvf nut0.tar   to untar into a new directory nut0.1/
4 Type: cd nut0.1           to go to the new directory nut0.1/
5 Type: nut0_install demo   to make nut0_demo in demo/
6 Type: y                   to run nut0_demo, if everything goes well so far
7 It will finish one full run in well under one second. It is fast!
8 Type: all    to plot all demo plots into file nut_demo_plot_out.dat
9 Type: nutpl nut_demo_plot_out.dat
  to see, with gnuplot, the sample nut0 output plots you just made.

Contents of NUT-0 distribution: 
in directory nut0.1/ you will find:
1. README file for online unix use
2. nut0_install  a script for installing any version (including demo) of NUT-0,
3. nut0_make  standard makefile for nut0
4. nutpl  a script for rendering nut0 output plots with gnuplot
5. rules/ directory containing various rules for different machines
   Currently tested machines/compilers are:
   a) alpha linux with Fujitsu fort compiler,
   b) SUN OS,
   c) HP compiler at hydra.gat.com,
   d) ABSOFT7.1 on a Windows PC
6. src/     All runtime NUT-0 subroutines in one folder. Contains
    All *.f files and *.i include files
    Main nut0 subs are all in nut0_subs.f
    Nut0_demo.f: Stand-alone demo program to run all NUT-0.
7. docs/ 
    Nut0Manual.pdf: This user manual in pdf format
    NUTPaper.pdf: pdf version of original NUT paper
    nut0_changes_aug03 : latest list of changes made to NUT0
8. dat/ data files
   These are also demo files: To demo calling NUT-0 from your program.
   You can copy the *.in files, and modify them for your case
    nut_demo_in.dat:        Runtime input data file for demo run,
    nut_diag_demo_in.dat    Runtime input for diagnostics
    nut_demo_out.dat
    nut_demo_plot_out.dat
    nut_diag_demo_out.dat
9. fs/ Sample flux surface shape *.f files
    nut_cyl_fs.f        Cylindrical flux surface
    nut_shafr_fs.f        Shafranov-shifted plasma
    nut_div_fs.f        Diverted plasma

To see some nut0 plots before you start: type "nutpl demoplots".
Get gnuplot 3.7 (free) or module load gnuplot if you do not have it.
Pick a plot number to render (needs gnuplot). Hit q to see next / quit.

Compiling and running NUT-0 demo   (or any other case):
 First compile Nut0 case demo by typing: nut0_install demo
 The script nut0_install does the following (for any case <casename>):
 1. Runs the correct makefile for your machine and <casename>,
 2. Makes the executable precompiler and runs it to make include files,
 3. Makes executable nut0_dem   (stand-alone version of nut0)
 4. Asks you if you wish to run it. 
    If you type y, it runs Nut-0 one time, then the output plotter, so   
    you can interactively plot any of the answers.
 5. The run generates following output files:
 a. nut_demo_out.dat: All NUT answers in a namelist format.
 b. nut_demo_plot.dat: Plots you made in gnuplot (table) format.

Calling NUT-0 from your routine: 
 3 logical steps (e.g., see Nut0_demo.f):
 1. call nut_start: [compulsory call] 
    Starts the nut0 system: sends all inputs to NUT-0 and 
    checks all pointers for consistency. 
    Call only one time.
 2. The next steps can be done in a loop without repeating step 1, 
    say during a time-dependent simulation. 
    You need to reset only things that have changed (plasma or external source).
    Nut_calculate will know what you have reset if you use the standard nut routines.
    a. nut_wall_source or nut_arb_source: Set external neutral source.
    b. nut_plasma: Set new plasma parameters. 
    c. nut_calculate: Core nut calculation.
 3. call nut_plot: [optional call] This interactively makes a file for gnuplot.

Thats it! You have successfully compiled and run NUT-0 (in < 1/2 sec !).

--------------------------------------------------------
Contents of geometry file used to build a new nut case:
 &NUTGEOM
 VERSION =  0.0000000E+00,
 PERCENT =  0.5000000    ,        % error in equating locations
 MX      =           6,            # of half grid points in x direction
 MY      =           6,            # of half grid points in y direction
 MZ      =           4,            # of half grid points in z direction
 MS      =           6,            # of secondary points on each ray
 MR      =           0,            # of radial fs pts, 0: all distinct fs's
 MF      =           2,            # of subgrid points in each flux surface
 MW      =          24,            # of wall points 
 MWW     =           4,            # of wall-to-wall ray points 
 WALCNTRL        =           0,        Method of wall specification
 FSCNTRL =  -1.000000    ,        Method of flux surface specification
 FSPARM  = 10*0.000000000000000E+000  ,    Parameters for flux surface shape
 MSEG    =           1,            Diagnostioc: # of site-line segments
 MBEAM   =           1,            Diagnostioc: # of neutral beam lines
 MBOL    =           1,            Diagnostioc: # of bolometer chords
 MDCX    =           0,            Diagnostioc: # of doubvle cx chords
 MHAL    =           1,            Diagnostioc: # of halpha chords
 XWAL    = 1024*0.000000000000000E+000  ,    X array of wall points
 YWAL    = 1024*0.000000000000000E+000  ,    Y array of wall points
 THWAL   = 1024*0.000000000000000E+000      Theta array of wall points
 /

--------------------------------------------------------
Note about all the "diagnostic routines" in nut:
  Original nut was developed for TEXT and TFTR use, 
  It was used closely coupled to the experiments, including
    diagnostic neutral beam, halpha measurements, 
    cx diagnostics, bolometers, etc. Many auxiliary "diagnostic"
    routines were added to facilitate its use.
  However, they are not in the "core" nut algorithm.
  I had to decide whether to remove them, even though some may be useful.
  For now, I have left all the "diagnostic" branch in nut0 as is, 
  I have not removed it, but I have also not upgraded it. 
  I suggest that you should not use the "diagnostic" branch 
    in nut0 for now.
  If you see something you like, let me know and we can activate it.
--------------------------------------------------------

Typical input data file to run NUT0 stand-alone:
(NOT USED if you call nut0 as a subroutine from your program)

&NUTDFLT
 PROMPT  =  1.                0:Prompts off, >1 more detailed
 UNITS   = 'MKS-19-EV'            Units used, MKS, den in 10^19, E in eV
 USERNAME = 'PMV'            Your user name
 fnames(1)='nut_demo_in.dat'        Names of i/o files to use
 fnames(2)='nut_demo_out.dat'
 fnames(3)='nut_demo_fs_in.dat'
 fnames(4)='nut_demo_xy_in.dat'
 fnames(5)='nut_demo_diag_in.dat'
 fnames(6)='nut_demo_plot_out.dat'
 fnums(1)=21                Unit numbers of i/o files to use
 fnums(2)=22
 fnums(3)=23
 fnums(4)=24
 fnums(5)=25
 fnums(6)=26
 MACHINE = 'TEXT(CYL)'            Machine name
 DISTYP  = 'LIMITER'            Discharge type
 TITLE   = ' '                Run Title
 LEGEND  = ' '                Plot legend
 RWAL    =  0.30            Wall radius (m)
 RLIM    =  0.26            Limiter radius (m)
 RMAJ    =  1.0                Major radius (m)
 TYPLAS  =  0                Plasma profile type
 TYPWAL  =  3.                Wall type
 RCOEF   =  0.0                Wall reflection coeff
 APLAS   =  1.                Plasma atomic weight
 ZPLAS   =  1.                Plasma atomic number
 AWAL    =  52.                Wall atomic weight
 ZWAL    =  26.                Wall atomic number
 ABEAM   =  1.                Beam atomic weight
 ZBEAM   =  1.                Beam atomic number
 BENERGY =  25000.            Beam main energy (eV)
 DI0     =  5.0                Central plasma density
 DIW     =  0.05            Plasma density at wall 
 DIA     =  1.                Plasma density profile coeff A
 DIB     =  0.                Plasma density profile coeff B
 TI0     =  800.            Same for ion temperature
 TIW     =  5.
 TIA     =  2.
 TIB     =  0.
 TE0     =  1000.            Same for electron temperature
 TEW     =  5.
 TEA     =  2.
 TEB     =  0.
 TAUP    =  6.E-3            Particle confinement time (s)
 TAUE    =  1.                Energy confinement time (s)
 SLIM    =  1.                Source at limiter
 SWAL    =  0.01            Source on wall
 SDIV    =  0.                Source in devertor
 SMEAN   =  1.                Average source
 BETASRC =  0.9                Source angular distribution cos(beta)
/

--------------------------------------------------------
NUT0 subroutines to call from your program and their arguments:
They are roughly in the order in which they should be called

1. Initialize whole nut system with:
        Subroutine nut_start( 
     &  nut_fnames, nut_fnums, nut_prompt,
     &  nut_names, nut_values, nut_delta, nut_r,nut_rxy,
     &  nut_xwal,nut_ywal,nut_rwal,nut_thwal,nut_error )

c       Note: All arguments are potentially both input and output
c             This allows NUT0 to guide you if anything is not set right
c             by returning the default or giving a suggested value.
c
c             User declares their dimensions either by using the include file
c             nut0_ucom.i that appears when you create a new nut0 geometry,
c             or can allocate them or whatever.
c             All names in nut0_ucom.i start with nut_ so as to avoid conflicts.
c             Not an elegant solution, I know, but will do for now.
c
c       inputs : 
c                nut_fnames(5) : nut i/o file names and  
c                nut_fnums(5)  : their corresponding unit numbers 
c                List of files that nut0 potentially uses nut_fnames(i):
c                1. Input data file for nut (e.g., nut0_demo_in.dat)
c                2. Output data file for nut (e.g., nut0_demo_out.dat)
c                3. Input Flux surface profiles (e.g. nut0_demo_fs_in.dat)
c                4. Input XY profiles (e.g. nut0_demo_xy_in.dat)
c                5. Input file for auxiliary diagnostics. (e.g. nut0_demo_diag_in.dat).
c                Note: These unit numbers will be used in "open" statements
c                      to open corresponding files.
c                      USER must make sure they do not conflict with any
c                      file unit numbers in his/her main or other subroutines.
c                      ANY CONFLICT IS NOT A NUT PROBLEM!
c
c                nut_prompt = 0 : silent mode, no prompts (i or o) from nut0
c                             1 : Only major prompts
c                             2 and higher : more detailed diagnostic prompts
c
c                nut_names()  : list of nut parameter names and 
c                nut_values() : their values that user wishes to set.
c                Note: These are lists of any nut parmeters and values you  
c                      may wish to set from your program.
c                      If you do not set any, the values read from the files
c                      will be returned to you so you can use them in your program.
c
c                Allowed nut_names are (upto 40 names):
c               'rwal','rmaj','rlim','typlas','typwal',
c               'rcoef','percent','prompt','aplas','zplas','awal','zwal',
c               'abeam','zbeam','benergy','di0','diw','dia','dib','ti0',
c               'tiw','tia','tib','te0','tew','tea','teb','taup','taue',
c               'slim','swal','sdiv','smean','betasrc','delx','dely',
c               'rplas','zeff','dnbcur','dnbvolt'/
c
c       output : nut_delta: grid constant, 
c                wall radius nut_rwal
c                Geometrical arrays (dimensions from nutucom.i): 
c                nut_r, nut_rxy, nut_xwal, nut_ywal, nut_thwal
c                nut_error = 0   All is well 
c                          = 1   Bad
c                          = 2   Very bad, etc.
c                Note: Nut0 is not terminated even if nut_error is not zero
c                      So YOU have to take proper action in your program.
c
c......................................

2. Set plasma profiles for nut with:
        Subroutine nut_plasma( nut_di, nut_te, nut_ti,
     &       nut_di2, nut_te2, nut_ti2, nut_error)

c       purpose: get plasma profiles from proper source and put them in
c               form usable by nut, then perform all preliminary
c               calculations which require these profiles.
c       relevent control parameters :
c               typlas : plasma type control switch (see below)
c               profile parameters di0,diw,dia,dib, ti0,tiw,tia,tib
c               plasma coefficient file, data file, or database names
c       if typlas = 1 or -1, profiles are given by user
c               if typlas = 1, 1d profiles are given by user
c               if typlas =-1, 2d profiles are given by user
c       otherwise, this routine gets the profiles and returns them to you
c               if typlas = 0, 1d profiles are made from coefficients
c               if typlas = 2, 1d profiles are read from data file
c               if typlas =-2, 2d profiles are read from data file
c               if typlas = 3, 1d profiles are read from data base
c               if typlas =-3, 2d profiles are read from data base
c               nut_error if plasma is not found
c......................................

3. Set wall source profile with:
        Subroutine nut_wall_source( nut_ewal, nut_swal, 
     &                              nut_phiw0, nut_smean)

c       purpose: Get/set given wall source into nut internal arrays
c       inputs : limiter and wall energies and sources
c                nut_ewal() = wall energy array
c                nut_swal() = wall source array
c                nut_beta   = coeff of beta for wall/limiter source
c       output : these values get calculated here, passed back to user,
c                and are also internally passed to nut.
c                nut_phiw0(mw,0:mz,mwe) = wall source
c               nut_smean  = average wall source (for ANTIC comparison)
c.............
3. Or set arbitrary source profile with:
        Subroutine nut_arb_source( nut_phip0, nut_phiw0)

c       purpose: set arbitray external sources
c       inputs : user supplied arbtrary external sources
c               nut_phip0(-mx:mx,-my:my,0:mz) : source in plasma
c               nut_phiw0(mw,0:mz,mwe) :external source on wall at all energies
c       output : none. these sources are just given to nut internal arrays
c......................................

4. Perform one nut calculation with:
        Subroutine nut_calculate( nut_iter,
     &  nut_phip, nut_d0, nut_p0, nut_q0)

c       purpose: calculate total neutral source by iteration
c       inputs : number of iterations nut_iter,
c               if nut_iter>0 start new iteration, else continue old one
c       params : total particle confinement time taup,
c               if taup>0, integral of source is matched to it
c               if taup<0, maximum of source is matched to it
c       output : calculated values of nut_phip,phiw,d0,p0,q0
c----------------------------------------------------------------------------

5. Calls 3,4, and 5 can be looped as needed. 
   For example, loop calls 4 and 5 if plasma does not change but source does.
c----------------------------------------------------------------------------

Auxiliary routines, not essential, but useful:
        Subroutine nut_save_main_par(fname)
c
c       action : saves all parameters and names in  file fname
c       inputs : filename fname where default is to be saved
c       output : none
c       note   : there is no inverse routine nut_read_default beacuse
c               you have to reset all internal quantities if you change
c               default settings. it is like starting over, so it can
c               only be done in nut_start.
c......................................

        Subroutine nut_change_one_param( name, nut_values, value)

c       purpose: change one nut parameter only
c       inputs : name of parameter to be changed and new value
c               array of parameters
c       output : none. the value is changed if name matches
c......................................

        Subroutine nut_change_one_filename( name, nut_names, value)

c       purpose: change one nut file name
c       inputs : name of name to be changed and new value
c               array of names
c       output : none. the value is changed if name matches
c......................................

        Subroutine nut_get_one_param( name, value)

c       purpose: get one nut parameter by name
c       inputs : name of parameter to get
c       output : value if name matches
c......................................

        Subroutine nut_get_one_filename( name, value)

c       purpose: get one nut name by name
c       inputs : name of name to get
c       output : value if name matches
c......................................

Optional diagnostic initialization call, not needed for core nut use.
For now, I have left the "diagnostic" branch in nut0, 
but I have not upgraded it. 
I suggest that you should not use the "diagnostic" branch in nut0 for now.

call nut_start_diag 
( nut_dinf, nut_plotpar, nut_beampar, nut_bolpar, nut_halpar )
nut_dinf, 
nut_plotpar, 
nut_beampar,
nut_bolpar, 
nut_halpar
--------------------------------------------------------------

Note that following extras are provided for your convenience only. 
They are NOT an essential part of NUT core, but you can use them if needed. 
1. plot script Nutpl and plot output routines to generate nut_plots
2. Reading and writing routines for standard nut I/O files.
3. NUT-0 stand-alone driver, demo, and diagnostic routines for nut.

REQUEST FOR FEEDBACK ON NUT-0: THE INITIAL TEST VERSION OF NUT
--------------------------------------------------------------
  NUT-0 is only the first step in developing an
     NTCC-compliant fast neutral code. 
  Although the neutral source can be 3-D, NUT-0 needs a 2-D plasma background. 
  We have chosen not to  wait until 
  this and other known NUT-0 limitations are overcome because 
  we wish to optimize the NUT development effort by:
  a. Getting feedback from actual users of NUT-0 to decide priorities,
  b. Allowing use of NUT-0 where its capabilities are already adequate,
  c. Enabling user-driven prioritization of NUT development.

Please email feedback to pvalanju@mail.utexas.edu

