README_ps_nbline

"ps_nbline" ("ps" for Plasma State; "nbline" for the name of the subroutine
that finds the start of beam neutral trajectories in NUBEAM).
This is a library module that could be connected to other software.

"ps_nbline_driver" is an example driver program.

A version of the NUBEAM nbline subroutine has been repackaged to get its beam
geometry and power, voltage, and species mix from the Plasma State only, and
is not dependent on the larger NUBEAM module.

"ps_nbline" requires as input a plasma state, and two passed routines to provide
random number generation (flat distribution and Gaussian distribution).  
In the example program "ps_nbline_driver" I use the Charles Karney MPI-compatible 
RNG software from http://w3.pppl.gov/NTCC numerical tools.  A "stream" 
argument is accepted, to allow multiple parallel RNG streams as might be 
needed in a restartable MPI application, and a "species" argument allows you 
to sample beam neutrals one species at a time, if desired, in case of 
multi-species NBI experiments.

It returns as output a data structure containing parameters for one beam 
neutral atom:  {Specie, Beam Index, full/half/third Energy index, (R,Phi,Z) of
start, and velocity (vR,vPhi,vZ) in MKS units}.  All are in a lab frame coordinate 
system with R the major radius, Z the elevation relative to a machine midplane
and where increasing values of Phi (and positive vPhi) progress 
counter-clockwise around the machine center line.

Choice of RNG software, and initialization thereof, is left to the "ps_nbline"
caller.  Ps_nbline choose particle start positions randomly with equal weighting 
proportional to the magnitude of beam currents into the torus from all injectors.  
Injectors are described by a source grid size and shape and location, aperture 
size and shape and location, divergence, focal length, power, voltage, and full-, 
half-, and (1/3)-energy current fractions for each injector.

One can generate a Plasma State from any time slice of any archived TRANSP 
experimental analysis or simulation run, using a program called "trxpl".  This
retrieves the beam geometry in effect for the selected run, as well as the 
instantaneous power, voltage, and energy fractions on each of the beams present
in the run-- i.e. all the data needed by "ps_nbline" (plus a bunch of stuff 
"ps_nbline" does not need, but other applications might).

Some caveats about the TRANSP data:  except for NSTX runs, most TRANSP runs lack 
the toroidal location of beam sources; for these runs the toroidal angle coordinate 
"Phi" will be computed as if all beam source grids were located at Phi=0 in th
laboratory frame.  (The neutral trajectories provided by "ps_nbline" are at the
 beam aperture opening into the vacuum vessel, not the source grid, so Phi won't 
be zero exactly).  Also, most existing TRANSP runs do not have geometrical data 
on all available beams; only the subset of beams with non-zero power for the 
shot simulated, are included.  We are moving in a direction where future TRANSP
runs will carry the full beam geometry description of all available beams even 
if not all are used in a given shot or simulation, but that is not where we are
at present.  Finally, although the Plasma State contains specification of the 
direction of toroidal current (i.e. "counter-clockwise viewed from above" or 
the reverse), many TRANSP users have in the past only been concerned with whether 
individual beams were injecting "co", with the current, or "ctr", against (for
beam aimings centered on the magnetic axis, this was sufficient for accurate 
simulations).  This means, though, that some TRANSP runs and their derived 
plasma states will have the wrong direction of plasma current combined with 
the wrong sign of vPhi of beam neutrals, so that "only" the co or ctr-ness of 
each individual beam is correct.

These caveats may be of concern if you are going to compute 3d effects.

-------------------------

Example of "ps_nbline_driver", for a tiny sample size.
 The arguments and values: 
"-ps", plasma state file
"-seed", random number seed in form of a character string
"-n", sample size.  
With larger sample sizes, you get closer to the expected energy fraction and co/ctr mixes.

ps_nbline_driver -ps:tftr_nbline.cdf -seed:abc -n:20
   argument no.  1: -ps:tftr_nbline.cdf
    argument no.  2: -seed:abc
    argument no.  3: -n:20
  
  ps_nbline_driver: syntax OK
  
  ------------------------------------ 
  RNG test results:
      frandm          fgauss
   1  4.50010516E-01  9.54309940E+00
   2  7.18333199E-01  1.17204567E+01
   3  5.25048820E-01  1.04145045E+01
   4  7.55693237E-01  1.02004305E+01
   5  3.18666724E-01  9.60477437E+00
   6  8.72751186E-01  9.80269201E+00
   7  1.29855160E-01  8.87728236E+00
   8  8.31454150E-01  8.67708024E+00
   9  9.43850719E-01  1.14250035E+01
  10  2.37133567E-01  1.10478839E+01
  11  9.72845561E-01  9.32498935E+00
  12  7.43387513E-01  1.04314225E+01
  13  4.00741842E-01  1.02622470E+01
  14  4.00277616E-01  1.03286282E+01
  15  6.50063801E-01  1.12435599E+01
  16  1.08780631E-02  8.59363494E+00
  17  7.00286196E-01  1.01747963E+01
  18  6.23248648E-01  9.17080061E+00
  19  8.08206244E-01  1.01316755E+01
  20  1.62234187E-02  8.61111097E+00
  21  7.92262033E-01  9.46932217E+00
  22  4.21848449E-01  1.04098390E+01
  23  9.76429074E-01  1.07312779E+01
  24  6.05808724E-01  1.02980799E+01
  25  4.41820946E-01  8.37151374E+00
  26  6.55106671E-01  9.23611368E+00
  27  5.97069260E-02  8.82862485E+00
  28  8.41814208E-01  9.58590151E+00
  29  6.03647844E-01  9.96678980E+00
  30  1.04597327E-01  9.26885227E+00
  31  9.64920938E-01  9.77263843E+00
  32  1.67712281E-01  1.11549240E+01
  33  2.92440867E-01  9.57128715E+00
  34  9.09841725E-01  1.11220171E+01
  35  9.59699111E-01  1.02416403E+01
  36  4.98057882E-03  8.11127411E+00
  37  1.95753395E-01  1.06179655E+01
  38  5.87201884E-01  9.70769104E+00
  39  1.88702178E-01  9.76436955E+00
  40  2.76439633E-01  1.04380348E+01
  41  9.15405774E-01  1.01519354E+01
  42  1.65489233E-01  9.58863337E+00
  43  1.70753562E-01  1.04283036E+01
  44  1.30009942E-01  1.09841057E+01
  45  9.75551003E-01  9.01113234E+00
  46  7.38616987E-01  9.94416185E+00
  47  7.08592535E-01  1.06629201E+01
  48  3.89803052E-01  9.58697980E+00
  49  2.46643776E-01  9.61960633E+00
  50  4.21602817E-01  9.52528339E+00
  
 frandm mean & rms deviation:   5.20443193E-01  3.08012625E-01
  
   Guassian sample over exp(-(x-xcen)**2/(2*xwid**2))
 xcen, xwid:   1.00000000E+01  1.00000000E+00
 fgauss mean & rms deviation:   9.91514583E+00  8.15161174E-01
  
  ------------------------------------ 
  Read the Plasma State: tftr_nbline.cdf
  
  The number of neutral beams:  7
  
  Check beam energy fractions...
  
  Name            co?  Pinj(W)       Einj(KeV)     F(full-E)     F(half-E)
 B_001             F    2.89019E+06   1.08665E+02   4.32616E-01   2.96263E-01
 B_002             F    2.74858E+06   1.06391E+02   4.38727E-01   2.93311E-01
 B_003             F    2.38328E+06   1.04528E+02   4.43777E-01   2.90880E-01
 B_004             T    2.42064E+06   1.06527E+02   4.38378E-01   2.93482E-01
 B_005             T    2.36997E+06   1.08742E+02   4.32398E-01   2.96362E-01
 B_006             T    2.65970E+06   1.08373E+02   4.33385E-01   2.95890E-01
 B_007             T    2.25763E+06   1.05660E+02   4.40713E-01   2.92362E-01
   Total Power (W):  1.773E+07 Co-inj fraction:  5.475E-01 Ctr-inj:  4.525E-01
  
 S   iB E co  Rsta       Phista     Zsta       vR         vPhi       vZ
 --- -- - -- ---------- ---------- ---------- ---------- ---------- ----------
 D    6 2 T   8.286E+00  8.508E-02 -2.201E-01 -2.213E+06  5.070E+05 -2.536E+03
D    1 3 F   8.357E+00 -7.838E-02 -6.732E-02 -1.816E+06 -3.860E+05  3.031E+03
 D    2 1 F   8.289E+00 -8.841E-02  1.666E-02 -3.093E+06 -7.438E+05  3.430E+03
 D    2 2 F   8.305E+00 -9.626E-02 -1.117E-02 -2.182E+06 -5.476E+05  1.502E+04
 D    1 1 F   8.366E+00 -8.323E-02  1.940E-01 -3.141E+06 -6.877E+05 -7.922E+03
 D    3 2 F   8.202E+00 -1.045E-01  2.178E-01 -2.143E+06 -6.166E+05  5.873E+03
 D    6 3 T   8.304E+00  9.397E-02  8.123E-02 -1.797E+06  4.528E+05  2.832E+04
 D    4 1 T   8.189E+00  1.102E-01 -1.713E-01 -3.055E+06  8.884E+05 -1.152E+05
 D    2 3 F   8.310E+00 -9.835E-02  8.990E-02 -1.779E+06 -4.578E+05 -2.408E+04
 D    1 3 F   8.362E+00 -8.101E-02  1.500E-01 -1.817E+06 -3.773E+05  3.894E+04
 D    6 2 T   8.301E+00  9.250E-02  5.335E-02 -2.202E+06  5.509E+05  5.428E+04
 D    3 2 F   8.207E+00 -1.067E-01 -1.983E-02 -2.146E+06 -6.030E+05 -3.330E+04
 D    6 1 T   8.309E+00  9.646E-02  1.549E-01 -3.114E+06  7.760E+05  8.039E+04
 D    1 2 F   8.351E+00 -7.508E-02 -2.458E-01 -2.226E+06 -4.568E+05 -4.719E+04
 D    5 2 T   8.361E+00  9.068E-02 -1.759E-01 -2.215E+06  5.147E+05 -1.961E+04
 D    4 1 T   8.180E+00  1.066E-01  4.059E-02 -3.055E+06  8.924E+05 -5.673E+04
 D    3 2 F   8.199E+00 -1.033E-01  1.293E-01 -2.151E+06 -5.846E+05  4.505E+04
 D    2 1 F   8.284E+00 -8.592E-02  2.210E-02 -3.094E+06 -7.391E+05  2.436E+04
 D    3 3 F   8.197E+00 -1.021E-01 -1.214E-01 -1.759E+06 -4.697E+05 -9.562E+03
 D    2 1 F   8.300E+00 -9.387E-02 -4.234E-03 -3.076E+06 -8.105E+05 -1.062E+03
  
full energy fraction:    3.500E-01
half energy fraction:    4.000E-01
(1/3) energy fraction:   2.500E-01
  
Co-injected power fraction:    3.839E-01
Ctr-injected power fraction:   6.161E-01
transpgrid.pppl.gov>

These are D beams from a Plasma State from an old TFTR TRANSP simulation.

