1 TRANSP
This document contains information on how to maintain and operate
TRANSP:  the time dependent tokamak transport and data analysis code.

Since TRANSP as a research code is under continuous developement there
can be no guarantee that the information contained in this help file
is complete and up to date.  However I will attempt to update contents
occasionally as time permits.

2 WWW_users
This information is for users viewing this file through a web
browser.

This is a HTML-ized VMS help document.  Some of the older information
is oriented to VMS users.  My apologies to UNIX users!  However, the
"Namelist" section is equally valid for UNIX and VMS.  (Note Apr 2002:
most VMS information, being obscolescent, has now been removed).

Sometimes this document will refer to text in another part of the
document with a statement like:

  see $ TRANSPHELP OPER NAMELIST NCLASS

WWW users can interpret this as follows:

  TRANSPHELP refers to the "root" of the document
  OPERations refers to a "1st level" subtopic, under the root.
  NAMELIST refers to a "2nd level" subtopic under OPERATIONS.
  NCLASS refers to a "3rd level" subtopic under NAMELIST.

which you should be able to find by following the presented outline
of HTML links.

2 Introduction

It is not necessary to have a deep understanding of all the physics
models in TRANSP in order to run TRANSP-- although it helps.  This
document does not describe the details of the physics models:  only how
to turn them on and off and what minimum information must be supplied
to control them.

TRANSP operational commands-- i.e. how to start a TRANSP run and how to
monitor its progress-- are also described in this document.

There is also information on code structure and maintenance, but much of
this is old (e.g. VMS oriented), has been moved to the bottom of the 
edocument, and should not be of interest to the average user.

2 UPDATE_NOTES

June 2009 -- NLREPLAY_HEATER & REPLAY_DATA_PATH controls allow heating
and current drive sources to be replayed from a prior run, instead of
being recomputed.

Updatable Namelist quantities (PTRANSP related, Mar 2009) -- see subtopic.
WARNING -- PTRANSP 2009 namelist updates incomplete, not ready for use!

LEVGEO=8 upgrade (Nov 2006) -- see subtopic.

PTRANSP upgrade (June 2006) -- see the subtopic.

NUBEAM module doc update -- McCune Oct 2004
Fusion Collaboratory Update -- Ludescher/McCune Apr 2002

date:  Oct 2004:  transp.hlp documentation of NUBEAM controls has been
cleaned up.  NUBEAM includes a new feature for automated timestep
adjustment based on accuracy criteria; DTN in TRANSP namelists (which
used to adjust NUBEAM timestep controls) is now ignored.

date:  April 2002:  TRANSP has been added to the Fusion Collaboratory
and can be run as a computational service at PPPL.  Documentation of
this service is under development; in the meantime interested potential
users should write to D. McCune (dmccune@pppl.gov).

Also new in 2002:  predictive features added to TRANSP:

  -- radiative loss model (based on Coronal Equilibrium)
  -- modern predictive transport models (GLF23 and MMM95 from the
     NTCC modules library).

TRANSP physics and other software packages are being made available for 
use outside of TRANSP, e.g. by other driver codes.  The famous TRANSP
Monte Carlo fast ion package is now available.  See:

   http://w3.pppl.gov/NTCC

3 Updatable_Namelist
[DMC March 2009]

To support PTRANSP applications, we have added a capability to allow
select namelist quantities to be updated during the course of the run.
Typically, the updatable namelist quantities are controls for the 
PTRANSP predictive transport model.

Such updates can be imposed asynchronously, by positioning a namelist
file with the name <runid>TR.UPDATE in the root directory of an active
run.  The updates will be picked up prior to the next time step, and a
record of the update is appended to <runid>TR.DAT.

Alternatively, such updates can be pre-scheduled by appending to the
end of the main namelist <runid>TR.DAT file text in the following 
syntax:

  ~update_time = <time-value>
  <update-name-value-pair>
  <update-name-value-pair>
  ...

A <runid>TR.UPDATE file can also contain a leading "~update_time"
record so that the update is received asynchronously but scheduled
according to the provided time within the simulation.  The time must
be at or after the current time in the simulation when the file is 
read.  The file can also specify a sequence of updates in multiple
blocks, in ascending order of time.

The <runid>TR.DAT file can also contain multiple ~update_time blocks; they 
must be specified in ascending order in time.  If an asynchronous update is 
received, this supersedes ALL ~update_time blocks at or after the time of 
application of the asynchronously received update.

If a run is restarted, <runid>TR.DAT is reread.  Update blocks at future
times will be applied based on the file contents at the time of reading
(these could be different thant they were at the start of the run).

Here is an example of use of prescribed update times:

  in the main namelist section:

    nmdifb=1   ! activate anomalous diffusion of fast ions
    nkdifb=3   ! impose on beam and fusion product ions alike

    bdifb=1.0e3  ! this & next line specify Db=1000 cm**2/s
    cdifb=1.0e3

  then at the end of the namelist file <runid>TR.DAT:

    ~update_time=3.5

    bdifb=3.0e3  ! this & next line specify Db=3000 cm**2/s
    cdifb=3.0e3

    ~update_time=4.2

    bdifb=1.0e4  ! this & next line specify Db=10000 cm**2/s
    cdifb=1.0e4

NOTE: in this example updates are shown which could have been prescribed
using an older set of namelist arrays {tdifba,bdifba,cdifba}.  For
quantities where multiple time update mechanisms exist, it is best not
to try to use more than one update technique in the same run; TRANSP 
error checking logic may enforce this by stopping the run.

Asynchronous updates are recorded as received, as "~update_time" 
prescribed updates in the active run's <runid>TR.DAT file, so that a 
rerun of the case with a copy of the namelist will see the same namelist 
update sequence.

4 Updatable_Quantities
Many namelist quantities are not expected to vary in time and 
therefore are NOT updatable.  Such quantities generally fall into
the following categories:

   Machine geometry descriptions (beams, antennas, limiters);
   Shot configuration information (species lists, direction of 
      toroidal field and current);
   Other information, the use of which has required a complicated
      initialization executed only once at the start of a run:
      for example, basic radial grid sizes like NZONES.
   Controls which could be updatable, but the code to implement
      the capability has not yet been written.

The updatable namelist feature is implemented as a separate namelist
containing a subset of the quantities in the main TRANSP namelist.

The current list of updatable quantities is defined in the TRANSP
source code in codesys/source/freeshare/port.spec.  The presence of
the tilda "~" symbol in a namelist quantity type specification 
indicates updatability.  For example:

   port.spec:  D  0  TINIT  =   0.05D0  ! INITIAL VALUE OF TA
   port.spec: ~D  0  FTIME  =   0.85D0  ! FINAL TIME

This indicates that the stop time of a simulation is updatable (but still
subject to time limits of available input data).  The start time is not
updatable.

4 Time_event_Tables
Generally, time-tabulated model controls are an older mechanism for
time dependent control of the TRANSP model that predate the development
of the updatable namelist.  The updatable namelist feature was added
to support PTRANSP.  Time dependence of some controls must be specified
through the updatable namelist when PTRANSP is active (specifically,
tabulated controls under TKEMOD, TKIMOD, and TVPHMODA cannot be present
when PTRANSP features are active).  Most time-tabulated controls in 
the namelist are not modifiable by an update namelist.

The balance of this section describes the existing time-tabulated 
model controls which came before the updatable namelist feature.

The existence of time dependent model controls serves several purposes,
such as:

  -- to only use diagnostic data when it is valid;

  -- to use experimental data to control a simulation for a period of
     time and then switch to predictive simulation part way through.

These control event tables are always optional; by default, "untabulated
controls" are used to specify an option to be applied throughout the 
entire simulation.

Each event table has an array of times (currently of maximum length (15))
specifying the time of application of a change in controls.

Because these table controls were developed at different times in the 
history of the code, and cannot now be redefined due to backwards 
compatibility requirements with existing namelists, the behavior of
the event tables varies.  For some tables the first time indicates 
when to switch from untabulated controls to table values; for others the
presence of table controls means the untabulated controls are never used, 
and the first time indicates when to switch from the 1st control set to
the 2nd control set.  In the former case, time (j) causes a transition
from time index (j-1) to (j); in the latter time (j) causes a 
transition from time index (j) to (j+1).  This will be illustrated
by example, below.

Because some table controls affect data (e.g. Zeff) that must be kept
continuous, the tables have various adjustable minimum spacings between 
event times.  The minimum time spacing generally only applies if the 
model change would force an unacceptable discontinuity.

Even where continuity is not an issue, all events times in a table must 
be separated by a minimum nominal dt of 1.0e-7 seconds.

The following control event tables exist:

  tqmoda(...) -- control model for q(x,t) or select predictive use
                 of poloidal field diffusion equation;

  tkemod(...) -- control electron transport model or select direct
                 use of Te input data -- legacy, not used with PTRANSP!

  tkimod(...) -- control ion transport model or select direct
                 use of Ti input data -- legacy, not used with PTRANSP!

  tvphmoda(...) -- control angular momentum transport model or select
                 direct use of angular velocity data -- legacy, not used
                 with PTRANSP!

  tzefmod(...) -- select data source for Zeff -- VB and "Magdif" Zeff
                 options not available with PTRANSP; setting of 
                 Zeff from impurity not available in PTRANSP run with
                 density prediction.

  trfrac(...) -- select specie recycling fractions;
                 (for PTRANSP use updatable RFRAC(...))

  tgfrac(...) -- select specie gas flow fractions;
                 (for PTRANSP use updatable GFRAC(...))

  tdifba(...) -- select anomalous transport model for fast ions;

These event tables have the following characteristics:

  event times  minimum separation  transition  use with PTRANSP
  -----------  ------------------  ----------  ----------------
  tqmoda       tauqmod             j -> j+1    unaffected
  tkemod       dtesave             j -> j+1     No
  tkimod       dtisave             j -> j+1     No
  tvphmoda     dtomsave            j-1 -> j     No
  tzefmod      dtzefmod(...)       j -> j+1    restricted
  trfrac        1.0e-7 seconds     j-1 -> j     No
  tgfrac        1.0e-7 seconds     j-1 -> j     No
  tdifba        1.0e-7 seconds     j-1 -> j    unaffected

The transition indication "j -> j+1" means that if table data is present
at all, the table data associated with event times controls the simulation 
at all times; the j'th event time is a transition from associated controls 
at index position (j) to (j+1).

Example of j -> j+1 control style (not a PTRANSP run):

   TINIT=2.0  ! start time of run
   TKIMOD=2.1,2.5
   NKIMODA=4,99,-4

The untabulated control NKIMOD is never used; NKIMOD=NKIMODA(1) from TINIT 
to TKIMOD(1)=2.1s; NKIMOD=NKIMODA(2) from TKIMOD(1) to TKIMOD(2)=2.5s, and
NKIMOD=NKIMODA(3) from TKIMOD(2) to the end of the simulation.

The transition indication "j-1 -> j" means that the code is controlled by
untabulated settings until the first event time; the j'th event time is a 
transition from the scalar controls or (j-1) index position to the (j)
index position.

Example of j-1 -> j control style (not a PTRANSP run):

  NVPHMOD=0
  TVPHMODA=3.0,4.0,5.0
  NVPHMODA=2,1,0

The scalar control NVPHMOD is in effect until TVPHMODA(1)=3.0s; then 
NVPHMODA(1) is used from TVPHMODA(1)=3.0s to TVPHMODA(2)=4.0s, etc.

3 LEVGEO_8_upgrade
The "scrunch2" program and TRANSP have been upgraded (Nov. 2006) to enable:

  A) Direct representation of inverse MHD equilibia as
       {R(theta,x;t),Z(theta,x;t)} (avoid Fourier series truncation).
       theta is defined in terms of equal arc length instead of
       a VMEC-derived formulation meant to minimize the number
       of moments needed.
       TRANSP is no longer dependent on the moments representation
       internally, using instead "xplasma" bicubic splines.
       TRANSP output (rplot) still has the output in moments form;
       the maximum number of moments is now 64.

  B) External field-- Psi(R,Z;t) can be extracted from EFIT via
       "scrunch2".  This is blended with the interior equilibrium, 
       however computed or read by TRANSP, with smoothing at the edge 
       of one grid spacing of the (R,Z) rectangular grid.  Future 
       upgrades of NUBEAM may allow accurate tracking of fast ion 
       orbits beyond the plasma boundary, using this data.  An (R,Z)
       guiding center integrator is being added to NUBEAM.

  C) Numerical limiter-- The EFIT {(R_i,Z_i)} piecewise linear contour
       can now be used as a limiter, e.g. for detection of fast ion 
       orbit loss.  When this is used it supersedes the traditional 
       "circles and infinite lines" limiter description from the
       TRANSP namelist.
  
3 PTRANSP_upgrade
4 PTRANSP_project
Note (2011): The PTRANSP project (as a separately funded grant) 
expired in 2010.  However, due to ITER and experimental project 
interest there will be some level of continuing effort to 
develop predictive capabilities of TRANSP (i.e. PTRANSP).

[Notes from July 2007]

The PTRANSP project (development of predictive upgrades for TRANSP)
resumed in July 2007.  This project is focused on predictive upgrades
to TRANSP itself.  Important upgrades, such as improvements to the two
temperature stiff solver, have been implemented.

PTRANSP-related TRANSP namelist variables will be described in the main
body of this document.

4 PTRANSP_Analysis_outputs
[D. McCune added this section Jan. 2011]

In many of the predictive options of PTRANSP the following sequence of
operations takes place at each time step:

   [acquire input data]

   if (predictive-run) then
      [execute prediction using transport equations]
   endif

   [analyze data using transport equations]

A series of multigraphs are generated to compare the transport 
(divergence of flux) employed by the predictive model with that 
seen by the analysis.  In each of these there is a profile of
"model" transport (from the predictive calculation) and "observed"
transport (from the analysis).  If no predictive calculation was
done the "model" transport profile will be identically zero.

If a predictive calculation was done, the two profile, while not
necessarily identical for technical reasons, should still match
closely.  If they do not-- please request a TRANSP developer to
examine the run (email: transp_support@pppl.gov).

In addition, for the ion and electron energy balance and for the
toroidal angular momentum balance equations where prediction is used,
there are multigraphs to compare thermal or momentum diffusivity 
profiles from the predictive model with those inferred from the
analysis.

The multigraph profile names are as follows:

   PTR_H, PTR_D, PTR_T, etc.:  single ion species particle balance
   EPTR -- electron particle balance
   IPTR -- summed main plasma ion species particle balance
   XPTR -- summed impurity ion species particle balance

   EETR -- electron energy balance
   IETR -- ion energy balance

   AMTR -- toroidal angular momentum balance

   KAPAN -- thermal diffusivity analysis (ions & electrons)
   CHIPHA -- toroidal angular momentum diffusivity analysis

The diffusivity analysis requires subtracting the non-diffusive 
(i.e. advective) contribution from total transport.  To evaluate this 
and get a match with predictive transport equation solution, any upwind
differencing must be taken into account.  The UPWIND multigraph
shows a set of dimensionless profiles representing the direction and
amount of upwind differencing applied (details are provided in a
separate section of this document).

4 TSC_server
DMC Jan 2011 -- this mode of operation has not been maintained and is
no longer available...

PTRANSP related upgrade -- June 2006.  TRANSP can now be configured to 
analyze results from a free boundary predictive tokamak model.  In TRANSP
terminology, this predictive model is known as a "Fusion Simulation
Project" (FSP) client.  TRANSP itself acts as a "Fusion Simulation 
Project" (FSP) server.  The services TRANSP provides are:

  (a) provide heating and current drive sources due to neutral beams,
      RF, alpha heating, and neutral gas sources.

  (b) carry out a standard TRANSP analysis of the predictive solver
      results (as if these were experimental data) and produce the
      standard TRANSP output database (NetCDF or MDSplus).

In its initial configuration, the FSP client will control the timestep
for updating sources and will need to provide providing the following 
time evolving data:

  (1) MHD equilibrium and poloidal field evolution
      (This includes the vacuum field, total plasma current, and the
      surface voltage).
  (2) Electron temperature and density
      (A particle confinement time tau(p) = N/gamma(a) must also be
      specified).
  (3) Ion temperature.
  (4) Zeff.

In addition it may optionally provide:

  (5) Toroidal angular velocity profile.
  (6) Profile of radiated power.

If these are omitted, TRANSP itself can either use input data or its 
internal predictive models to compute their evolution.

In this mode, of course, one is not really "using" TRANSP, but rather,
using the code which calls TRANSP services.

We have implemented this for the PPPL TSC code.  Users provide TSC 
namelists and use TSC tools to view code results, but TRANSP data is
also produced.

This is work in progress.
2 Documentation
Other sources of information (besides this HELP file) are available
to figure out what is going on in TRANSP:

TRANSP webpage:

   http://w3.pppl.gov/transp

National Transport Code Collaboration webpage (where many TRANSP
code components are available for download):

   http://w3.pppl.gov/NTCC

People collaborating on TRANSP development projects also have access
to the source code.  Most TRANSP sources have a lot of internal 
documentation.  Of particular interest will be:

   source/freeshare/port.for -- TRANSP COMMON & namelist specification
                                including default values.

   source/outcor/plotgen.i   -- TRANSP output data specification

   source/misc/trdatgen.spec -- TRANSP input data specification

and possibly also:

   source/tr_vaxdata/dprset.for -- TRANSP (trdat) namelist defaults

For those not engaged in code development, the above can also be
found at 

   ftp://ftp.pppl.gov/pub/transp/codata/gen

A number of plaintext documents are available in source/doc/* which
are also mirrored at

   ftp://ftp.pppl.gov/pub/transp/codata/doc

In this archive some documents of particular interest might be:

   trintro.doc -- a short (3-page) introduction to using TRANSP.
                  (somewhat dated)

   sampletr.dat -- a sample namelist (dated but gives a general idea).

   refs.doc -- references to published scientific literature related
                  to TRANSP.

And there is much additional information covering a wide variety of
topics.

The BEST source of information on TRANSP would be talking with current
expert users and developers.  People at PPPL with greater or lesser 
familiarity with various aspects of TRANSP are:
  D. McCune  R. Budny   S. Kaye
  R. Andre   M. Gorelenkova   C. Ludescher-Furth   X. Yuan

2 Operations
choose subtopic--

 If you have your namelist and Ufiles already, and want to start a
 TRANSP run, see the section TRANSPruns.

 TRANSP run id's have been generalized to allow a shot-try format.
 See the section Run_identification.

 All TRANSP software supports both the old and new format run id.
3 Introduction
  So you want to make a TRANSP run?  You need two things:

  (a)  access to high quality tokamak data

  (b)  the time and patience to learn how to use the TRANSP namelist,
input data preparation tools, and output data display tools.

  TRANSP and supporting codes constitute a large system.  It is 
essentially a collection of physics and empirical data processing
knowledge.  The complete system encompasses a about a million
lines of FORTRAN, over 100 executable programs, over 100 subroutine
libraries.  Just TRANSP itself contains 500,000 lines of FORTRAN,
over 2000 subroutines, and up to 1000 named quantities in its plot 
output database.  Mastery over this system is not won with only 
one or two days' effort.

[Editorial note -- above code size estimates are from the 1990s.  As
of March 2011, the total size of the code for the TRANSP system, i.e.
TRANSP itself plus supporting tools, is about 2.4 million lines of code].

  On the other hand, the effort may be worth the cost.  TRANSP is often
the best tool available for time dependent analysis of tokamak data.
Just going through the process of gathering and preparing a self-
consistent data set for a TRANSP run is often very instructive,
revealing much about the quality of the data.  The analysis itself 
then yields a vast amount of information.  If the data holds up under 
analysis, then the TRANSP output database can serve as the starting 
point for numerous quantitative comparisons with theoretical plasma
physics models, giving a point of contact between theory and experiment.

  For purposes of getting started it is probably best to work first
with an experienced TRANSP user.  This HELP file is probably most
useful as a reference for those who already have considerable
familiarity with the system.

3 MDSplus_Run_identification
In 1999-2002, TRANSP i/o was generalized to allow operation with data
sharing over the network, based on the MDSPlus software of the MIT
Plasma Fusion Center.  (see http://w3.pppl.gov/transp/MDSPLUS ).  A
"standard MDSplus TRANSP tree" was agreed to by the major U.S. fusion
labs (PPPL, GA, MIT, see: http://w3.pppl.gov/transp/MDSPLUS/tree.html ).

Although PPPL TRANSP runs (even in MDSplus) continue to be identified
using the traditional "tokamak.year shot-try" nomenclature, other labs
have chosen a more MDSplus oriented approach, in which archived TRANSP
runs are associated with an MDSplus experimental "shot tree", and each
distinct TRANSP run is given a separate subtree name such as "TRANSP01",
"TRANSP02", etc.  However, the precise method for run identification
is basically under the control of the TRANSP client site, and it does
vary from lab to lab, although MDSplus based accessibility is now 
standard.

All PPPL tools for looking at TRANSP output can access TRANSP results
in the traditional method (via files on a local disk) or by the new
MDSplus method (from MDSplus servers over the internet).  Many of the
traditional TRANSP client tools (such as "rplot" and "ufiles" software)
are available for download from the PPPL National Transport Code
Collaboration (NTCC) website:  see http://w3.pppl.gov/NTCC .

3 PPPL_Run_identification
  Complete identification of a PPPL TRANSP run requires the following
information:

  (a) a tokamak acronym (3 or 4 characters)
  (b) a two-digit shot year code
  (c) a run id:  either the old four digit run number or the new
shot-try identifier.

  The following are examples of complete TRANSP run ids:

  TFTR.84 9900       (TFTR, 1984 shot data, 4 digit run id 9900)

  TFTR.88 35782P02   (TFTR, 1988 shot data, shot-try run id
                      35782P02 which in the PPPL usage indicates
                      a predictive run based loosely on data from
                      TFTR shot 35782)

  A complete run id can be used for at most one TRANSP run.  At PPPL
the program $ GETRUN can be used to determine what runs exist and
where the data is stored (i.e. on magnetic disk, optical disk, or
tape).
4 Shot_Try_Identifiers
  Introduced in 1990, the eight character shot-try string is the
new, preferred way of labeling TRANSP runs.  The shot-try string
has the format

  nnnnnCmm   (typical), or
  nnnnnnCmmm (with 6 digit shot number and 3 digit try number).

where:

  nnnnn  is the 5 or 6 digit shot number (identifies the tokamak shot)
         6 digit variant cannot have a leading zero.

  C      is a one character run classification code (A-Z).

  mm     is a 2 or 3 digit try number used to distinguish different
         runs of the same class on the same data.  The 3 digit try
         numbers cannot have leading zeroes.

TRANSP users or user groups may use the one character run class-
ification code in any way they see fit.

For example, the PPPL TFTR group used A for analysis, P for
predictive runs, and Z for code testing or debug runs.  Thus the
run id 35782Z90 corresponds to a debug test run.  However, this
is a local convention of use and is not in any way imposed by
the TRANSP code system.

4 Four_digit_Run_numbers
  Prior to 1990, the four digit run number was the only mechanism
available for the labeling of TRANSP runs.

  The newer shot-try run identification scheme should be used in
preference to the four digit run number.  However, the four digit
run number is still supported and will continue to be supported in
TRANSP and related codes.

  Selection of run numbers for TRANSP runs is entirely in the hands
of the operator(s) of TRANSP.

  Suggestion (if you must use the four digit run number):  
for each new "shot" or data set, "allocate" 20 unused run numbers for
that shot.  For example:  for shot 12345 allocate run numbers 1220
through 1239.  TRANSP run numbers are always 4 digits long, i.e.
between 1000 and 9999.  The first run number in the TRANSP run
"series" for shot 12345 would be 1220, the second 1221, etc.  For
major changes in the input data one might skip to numbers 1230, 1231...
or perhaps allocate a fresh set of 20 run numbers.

  Reusing run numbers for runs on data from the same tokamak and year 
of shot is not recommended.

  If more than one user is working on data from the same tokamak shot
year, special caution must be employed in selecting run numbers, to 
avoid conflicts.

3 PPPL_VMS_legacy
The old TRANSP system used to run exclusively on PPPL VMS machines.
The system has long since been ported to unix, and, recently, the
last VMS TRANSP run production system was turned off.

However, PPPL TRANSP results can still be accessed on the PPPL VMS
machines...

4 Disks_VMS
TRANSP results data (from completed runs) reside on disks identified
by the logical name RUNDATA:

TRANSP run documentation resides on a disk identified by the logical
name TRINF:

TRANSP code and procedures reside on a disk called TRHOME:.

Users that do not execute the TRANSP LOGIN procedures can also use
the system wide TRANSP$ logical name to access TRANSP utilities:
TRANSP$:[COM] is synonymous with TRHOME:[TRANSP.COM] (a directory
of TRANSP DCL procedures).

4 Directories_VMS
(read the section on disks first!)

At PPPL (Apr 2002) the following tokamak directories are known:

  PLT  PDX  PBX  PBXM TFTR NSTX 
  ASDX AUGD BPX  CIT  D3D  DIII FIRE HL1M ISX  ITER JET JT60
  JULI MAST NCSX TORS TXTR WRK

Ufile data directories --

TRANSP provides a default set of directories for input data.
UFILES physics input data are stored in subdirectories
TRHOME:[TRANSP.<tok>.DATA], also conveniently accessible via the
LOGICAL NAMES <tok>_DATA.  All TRANSP runs analyze data from one
nominal shot (namelist item NSHOT) although the data itself may
represent an amalgam from several actual shots.  The shot number
NSHOT must be imbedded in the filename of all UFILES to be used
in a given TRANSP run.

It is possible and may be desirable to create more directories 
for input data storage.  At PPPL we do this for TFTR data. TFTR
UFILEs are stored in areas TR_DISK:[name] where "name" is the 
name of the physicist preparing the input data for TRANSP.
TRANSP run namelists are modified to specify where to find the
UFILE input data.

TRANSP run results directories --

Files for COMPLETED TRANSP runs are stored in subdirectories
RUNDATA:[TRANSP.<tok>.<year>] where <year> is a two-digit code 
constituting the last two digits of the YEAR of the SHOT.

After a period of time, runs are removed from the RUNDATA:
magnetic disks, because of limitations of storage space.
However, the run's documentation file (xxxxTR.INF) and its
input namelist (xxxxTR.DAT) are retained on disk and may be 
found in the directory TRINF:[<tok>.<year>].

Example:  The TRANSP run TFTR.90 46470Z02 ...

  completed results resided in RUNDATA:[TRANSP.TFTR.90]
  information on the run can be found in TRINF:[TFTR.90]46470Z02*.*

At PPPL the program $ GETRUN can be used to restore migrated runs.
Runs on laser disk can be restored by reference with $ RPLOT.

3 Unix_workstations
Unix based TRANSP development systems and production systems
are now the norm.  Documentation for unix based systems
is found largely in files found in the source distribution
under codesys/source/doc.  See for example unix_transp.doc.

For general information on setting up a UNIX TRANSP system,
see also anonymous ftp at:

   ftp::ftp.pppl.gov:pub/transp/codata

start with the README file.

4 Directories_Unix
TRANSP run results directories --

Output files for COMPLETED TRANSP runs are stored in subdirectories
$ARCDIR/<tok>/<year> where <year> is a two-digit code 
constituting the last two digits of the YEAR of the SHOT.

Namelists and inf files are stored in $TRINF/<tok>/<year>

3 Programs
The following programs are used in the process of creating a TRANSP 
run.

  ** this section to be updated (dmcApr16) **
  ** for PPPL and Collaboratory Users **
  ** VMS/UNIX differences to be noted (dmcApr16) **

  RPLOT -- interactive program to look at TRANSP plot output.  Also
           runs in batch to produce standard hardcopy plots.

           Define Environment TERMINAL_TYPE
           xterm -- "xterm" terminal emulator
	   XTC   -- "xtc" terminal emulator 

  XTRANSPIN -- GUI to prepare a Namelist for a Transp run and submit the run.

4 RPLOT_PostScript_file
To produce a PostScript file define environment "PLOT"
 (e.g. export PLOT=',foo.plt-ps')
 See http://w3.pppl.gov/~pshare/help/body_sg_hlp.html

 Note: tek2ps_sh and tek2ps must be in your $PATH
       tek2ps.pro should be in /usr/ntcc/etc, $cwd or in $TRANSP_LOCATION



3 Programs_UNIX
The UNIX TRANSP developer with a standalone system will typically use
the following programs:

  pretr -- set up scripts for a TRANSP run
  trdat -- examine input data for a TRANSP run
  runtr -- execute a TRANSP run

A UNIX TRANSP user in a shared local UNIX production system may
use commands as described in the user interface section of 

   codesys/source/doc/tr_start.doc

which if you need help finding you should ask the person at your site
who is acting as keeper of the TRANSP production source code.

See also:    http://w3.pppl.gov/transp/production.html

Note: JET has its own locally developed TRANSP production system.

3 Files

INPUT:  namelist and physics data
        1234TR.DAT, UFILES, (optional) 1234EX.FOR for special code
        --all the above can now be in an MDSplus tree instead.

PERMANENT OUTPUT in VMS RUNDATA:[TRANSP.<tok>.<year>]
        or UNIX $RESULTDIR/<tok>.<year>

    traditional format:
        1234TF.PLN -- plot data map and labels for RPLOT
        1234MF.PLN -- profile plot data for RPLOT
        1234NF.PLN -- scalar plot data for RPLOT

    NetCDF format:
        1234.CDF -- all of the above in a single portable binary
                    random access NetCDF file.

        --or, output may be stored in an MDSplus tree instead

During execution, TRANSP creates and removes a sizable collection of
temporary files.  There are also some relatively seldom used special
purpose output files which are not documented here.

3 UFILES
physics data input to TRANSP.  stored in a directory indicated by
the INPUTDIR variable in the TRANSP namelist... or instead, input
signals may now be stored in MDSplus.

Ufiles help is available via the http://w3.pppl.gov/NTCC or
http://w3.pppl.gov/transp webpages.

4 Utilities
(these tools, which are used to prepare TRANSP input data, in the
past read and wrote Ufiles but can now also read/write to MDSplus).

(note -- the program names are in lower case on UNIX systems).

(Apr 2011 note: the programs listed in this section are all very old, 
dating from the PPPL TFTR epoch or even earlier than that.  Some folks 
still use them.  Others have switched to using their own IDL procedures 
and scripts for data preparation, or, non-PPPL sites have provided their 
own sets of tools adapted for local needs.  Many of the capabilities of 
these tools are imbedded in libraries that can be made sharable and can 
be coupled to scripting languages.  For discussion of possibilities 
along these lines, contact the PPPL TRANSP team, transp@pppl.gov).

GSMOO1 - SMOOTH 1d UFILES
GSMOO2 - SMOOTH 2d UFILES

  GSMOOn routines also allow various types of smoothing,
removal of glitches, "units transformations" (i.e. linear transforms 
f-->a*f+b for any axis of the data), and in GSMOO2, an interchange 
of axes f(x,y)<-->f(y,x).

GAVER1 - AVERAGE 1d UFILES
GAVER2 - AVERAGE 2d UFILES

  Input UFILES to the GAVERn routines should contain equivalent data
units appropriate for averaging.  The meaning of the dependent and
independent axes of the inut data files should be compatible.
In 1986 the GAVERn utilities were upgraded so that precise matching
of independent axes of input data is no longer required.  The first
input file determines the axes for the output file; subsequent input
files have their data interpolated to this fixed grid.
  Also in 1986 variable weighting and data summing options were added
to the GAVERn programs.

UGRAF1 - PLOT 1d UFILES
UGRAF2 - PLOT 2d UFILES

PROPANE - GENERATE hand-entered or analytic shaped UFILES

EXTRAC - EXTRACT subset UFILES from 2d input UFILE.
  EXTRAC permits extraction of 1d UFILE "slices" with averaging options,
or 2d "blocks" with sections of the original 2d UFILE deleted.  Useful
for removing bad sections of data, or taking the "most useful" part of
a 2d UFILE and creating out of it a simpler to use 1d UFILE.

CONCAT - CONCATENATE a series of 1d UFILES into a single 2d UFILE.
  Used e.g. to join a series of Thompson Scattering profiles (1d vs. r
at individual times) to form a profile evolution file vs. r and t.
The 1d input UFILES must have the same x axes (no. of pts and values)
and each must contain a scalar from which the 2nd independent axis is to
be constructe
  CONCAT can also be used to add additional profiles or time series to
existing 2d Ufiles.

New 1986 Utilities:
SPLICE1 - splice 1d UFILES to form new 1d UFILE.  E.g. read in a series
of time trace UFILES, specify time intervals and associate a file with
each interval; plot the result and/or write as a new UFILE.  Sample 
application:  splice neutron detectors so that the best count rate
detector is in use at all times during a shot.
SPLICE2 - 2d analog of SPLICE1

UFILES utilities are described in more detail in the UFILES manual
(D. Mc Cune's office).  All utilities are interactive menu driven 
programs.  All use UREAD for control input and so may be readily
adapted to batch mode use for automatic processing of large amounts
of similar data (for UREAD HELP info type $ URHELP).

UFILES utility experts at PPPL:  R. Budny, D. Mc Cune, M. Zarnstorff.

3 NAMELIST
The TRANSP namelist file nnnnTR.DAT actually contains two namelists:

(1)  TRDAT namelist.  Define UFILEs input data to TRANSP.  Specify
certain data options, e.g. normalization of density profile data.
The TRDAT namelist contains CHARACTER data and is not read by
TRANSP.  All entries in this namelist are described under the
subtopic TRDAT.  TRDAT is the input data preprocessor for TRANSP.

(2)  TRANSP namelist.  All TRANSP options.  This namelist is read by
both TRDAT and TRANSP.

When a TRANSP namelist switch setting requires availability of UFILEs
data for TRDAT this fact is stated but the specifics of how to make
consequential modifications to the TRDAT namelist are not repeated.
see the TRDAT subtopic.

NOTE: in places the documentation refers to files in the TRANSP 
source distribution.  Some of the more commonly referenced objects
are described above in the section on "Documentation".  For other
items-- if you do not have access to the TRANSP source but need it,
contact Doug McCune at PPPL (dmccune@pppl.gov) (noted 16 Apr 2002).

... choose subtopic
4 Templates
It is highly advisable to use the namelist of a recently completed
TRANSP run as a template when preparing a new run.  If you are new
to TRANSP namelists it is instructive to examine an existing namelist
file.  The file contains inline comments preceded by the comment
character "!".  (The file is not in FORTRAN namelist format; it is
sorted and transformed before actually being read in by any FORTRAN 
NAMELIST READ statement).

4 MPI_TRANSP

(new DMC Feb. 2009)

TRANSP has an emerging MPI capability.  Selected component(s) of TRANSP
have been MPI parallelized.

Making an MPI TRANSP run involves two steps:

  (a) selecting which components are to be run in MPI mode, and how;
  (b) submitting TRANSP with resources to support an MPI run requested.

There are two modes for MPI TRANSP runs:
  (1) TRANSP itself is a serial process; it invokes MPI jobs-- e.g. 
      time step advances on neutral beams-- as subprocesses; or
  (2) TRANSP itself is an MPI process; it invokes MPI jobs are handled
      within memory through subroutine calls if the code allows; otherwise a
      subprocess is used.

A third mode, where the MPI job is sent to a separate server, is under
investigation but is not currently reliably supported.

5 Selecting_MPI_components

Namelist controls:

Integers:
  NBI_PSERVE -- NUBEAM (neutral beam and fusion product fast ion model)
  NTORIC_PSERVE -- TORIC (ICRF full wave model)

(...coming soon: NPTR_PSERVE: PTRANSP parallel solver...)

Values and their meanings:

  xxx_PSERVE = 0  -- (default) -- no MPI, run in serial model

  xxx_PSERVE = -1 -- run as separate sub-process in MPI mode; use
                     available processors; sometimes used in a serial
                     run for sub-process I/O testing.  Serial version
                     of TRANSP runs; communicates with MPI subprocess,
                     a separate program, by file exchange.

  xxx_PSERVE = 1  -- run within MPI TRANSP executable; use available
                     processors.

Some combinations might not be supported.  Here is what is supported
as of 15 May 2011 (DMC):

PSERVE value:      0    -1    +1  
==================================
NBI_PSERVE        yes   yes   yes 
NTORIC_PSERVE     yes    NO   yes

Global rule #1:  If MPI resources are detected within a TRANSP run, they 
  must be used: at least one xxx_PSERVE variable must have a value of +/-1.

Global rule #2:  If no MPI resources are detected within a TRANSP run,
  xxx_PSERVE values of +1 are not allowed.  A value of -1 will result in
  a serial subprocess-- this is used for I/O testing but is a poor choice
  for users due to performance reasons.

5 Requesting_MPI_TRANSP_run

For tr_start/tr_send users:

(A) in namelist set xxx_PSERVE = 1 for each desired MPI-parallel component:

    Examples:
       NBI_PSERVE=1     ! MPI version of NUBEAM
       NTORIC_PSERVE=1  ! MPI version of TORIC

    Additional MPI components will be added over time.

(B) follow guidelines for reasonable use:

    i.  For NUBEAM, linear cpu performance scaling needs ~4000 ptcls/cpu.
        So for an MPI run with 10cpus, use NPTCLS=40000 or more.  Fewer
        particles may suffice if certain expensive options are used, 
        such as NLBGFLR=.TRUE., enhanced NUBEAM FLR model.

   ii.  For TORIC, NMDTORIC=127 and up should use parallel service.
        NMDTORIC=63 may use a few cpus e.g. Np=4;
        NMDTORIC=31, leave as serial.

(C) During tr_start / tr_send sequence, you will be prompted for the 
    number of cpus you want.  If you ask for more than about 16, you 
    may face a long queue wait (PPPL production system as of Oct. 2009).

4 Source_Playback_Option

TRANSP/PTRANSP have incorporated the SciDAC "Plasma State" software to
support a playback option.  This allows "sources" from a prior TRANSP
run to be used in a subsequent TRANSP run.  Since the sources are read
from existing data rather than recomputed, the playback run can often
complete much more rapidly than a run with an original source calculation.

By "sources" is meant:
  heating by neutral beams, all types of RF, and fusion products;
  momentum sources (mainly neutral beams);
  particle sources (neutral beams, fusion products)
  current drive by neutral beams, all types of RF, and fusion products.

  Also, the density and pressure from fast ion species is read from
  the playback data, affecting depletion and MHD equilibrium solution.

A series of runs made with this option can be assured of getting the same
sources-- this feature might well be useful e.g. for studies of transport
models, differences in MHD equilibrium solvers, etc.

To activate this feature, set:

  NLREPLAY_HEATER = .TRUE.
  REPLAY_DATA_PATH = <data_path> (CHARACTER*128)

    For Fusion Grid runs, the MDS+ option must be used for <data_path>:

       MDS+:<server-address>:<tree-name>(<MDS-number>)
         --or--
       MDS+:<server-address>:<tree-name>(<tok.yy>,<runid>)

    For example:

       MDS+:_transpgrid.pppl.gov:TRANSP_TFTR(TFTR.88,37065D04)

    For code development testing, a FILE option also exists, i.e.
    FILE:<path-to-run>.

Other namelist changes should not change the plasma species or the 
description of the heating sources (i.e. the number of active neutral
beams and RF antennas cannot be changed, since the sources are being
prescribed from a prior run that was based on these settings).

REPLAY_DATA_PATH must refer to a run that contained an actual calculation
of the sources.  It cannot refer to another playback run.

The accuracy of playback is constrained by the output time resolution
that was selected in the run containing the original source calculation.
To test accuracy, replay the original run with no other namelist changes
other than NLREPLAY_HEATER and REPLAY_DATA_PATH.

Detailed output from source models-- e.g. non-Maxwellian distribution
functions or time slice wave field information-- is not available in 
playback runs.

5 Collection_of_Plasma_State_time_series

There is an option to archive the collection of Plasma States gathered
in course of execution of a NLREPLAY_HEATER=.TRUE. run.  The idea here 
is to provide the same input data to another code, such as a SciDAC FSP
prototype code, which can read Plasma State files.  Then, by this 
method, common profiles can be shared between TRANSP/PTRANSP and the
FSP prototype (i.e. for cross code comparison purposes).

NOTE: this is expensive in disk space and so is not recommended unless
done for a specific research purpose.

The options are:

   NOPTION_SAVE_STATES = 0  (default) Plasma State data not saved.
   NOPTION_SAVE_STATES = 1  Save Plasma State sequence containing 1d data.
   NOPTION_SAVE_STATES = 2  Save Plasma State sequence containing 2d data.

The =1 option saves the heating and current drive sources and the evolution
of temperatures and densities of the original run which contained the full
source calculation.  

Archived filename: <runid>_sces_pseq_TAR.GZ -- gzip'ed tar file.

The =2 option contains everything in the =1 option, plus the MHD equilibrium
and fields, with associated 1d metric data.  This size of the collection is
about 30x bigger than the =1 option collection.  It includes "nominal"
free boundary data and G-eqdisk files, but, accurate free boundary data is
available only if input to the original run (via EFIT) or if produced through
use of an accurate free boundary equilibrium within PTRANSP (a feature 
planned but yet available as of June 2009).

Archived filename: <runid>_eqsces_pseq_TAR.GZ -- gzip'ed tar file.

Because of the reduced equilibrium metrics in the =1 output file, there
will be a tiny difference in the source profiles between these two options.

The files can be unpacked by the TRANSP script "fi_gzn_unpack".
Recommended procedure:

  a) create empty working directory & cd to this directory;
  b) fi_gzn_unpack <archived-file-path>
     (contents are unpacked into a subdirectory named <runid>_replay).

If fi_gzn_unpack is not conveniently available, here is the script code
which can be done by hand; 1st line is pseudo-code:

  set filename = (the actual file path)

  set tmptar = "tmp.tar"

  cp $filename ./$tmptar.gz
  gunzip $tmptar

  tar xvf $tmptar

  rm $tmptar

4 RESTART_RECORDS
As a reliability feature, TRANSP writes RESTART records.  The data
in the restart records allows the TRANSP job to be restarted in case
the computer on which the job is running crashes.  On the VAXs this
is usually done automaticly.

However, the writing of these restart records can be time consuming.
Therefore, set
  MRSTRT= n  
to write restart records only once every nth plot output record,
or, even better, set
  MRSTRT= -m
to write restart records only once for every m minutes of cpu 
time consumed.  The default is MRSTRT = -20.

If a job is stopped and restarted, and MRSTRT.GT.1 or MRSTRT.LT.0
was used, then, the run output data may contain duplicate time points.
The plot post-processor program POPLT2 removes them while converting 
the data to binary form for RPLOT access.

To completely suppress restart records set MRSTRT=0.  This is
not recommended.

DMC May 2003: the user value of MRSTRT will be overridden and
set to -1, if ELVIS runtime graphical monitoring is enabled (see 
next section).

4 Steering

 (this section not finished)

It is now possible to restart a TRANSP run under a new runid with 
modified input data-- a capability generically referred to as
"steering" a run.  The procedure for this is

  (a) interrupt the TRANSP run to be restarted.  This can be pre-
      programmed using stop times TABORT(...) in the namelist, or
      it can be requested on the FusionGrid while the run is still
      executing (how?).

  (b) submit a new run with modified namelist, which references the
      original run (a) but provides input data that is modified; the
      modifications apply only to times after the time of interruption
      of the original run.

The set of allowed changes for such a modified restart namelist is
limited.  The revised input data is merged, i.e. combined from the
original run for times prior to its interruption, and taken from the
new run namelist for times after the interruption.  This merger is
executed by the TRANSP data acquisition front end program, trdat.  
Therefore, only namelist changes which modify the data seen by trdat 
are allowed.  These are generally:

  -- names of Ufiles or MDS+ signals containing input data
     i.e. input data (e.g. electron density, Zeff) can be changed
     on this type of restart, the change only applying after the 
     restart time.
  -- neutral beam powers and voltages (and on/off times)
  -- RF antenna powers (and on/off times)
  -- stop time of run
  -- future interruption (TABORT) times in the run
  -- model control time events, if present in the original run.

Anything else, such as, generally, controls for the TRANSP simulation
such as which variant of neoclassical bootstrap current and/or resistivity, 
etc., can NOT be changed on restart.

(A tool will be provided to assist with construction of a restart
namelist, and to check the validity of a namelist intended to be
used for a restart with modified data).

The namelist for the modified run will contain explicit references
to the original run:

  old_transp_run = <path-to-old-run> (character string)
  old_transp_time = <time to which old-run plasma data is valid>
  old_transp_stime = <time to which old-run source data is valid>
  blend_time = <transition time interval to new data>

(need to describe how to specify MDS+ path to old_transp_run data).

Although a run can reference it's own input data, that input data will
be modified when the restart executes-- and therefore, this is not 
recommended.

The default value for "blend_time" is 0.01 seconds.

Since the input data of the original run is now archived separately,
the namelist remains valid after the restart run completes, i.e. the
calculation can be rerun from the beginning under a 3rd runid, and 
will see exactly the same hybrid data, part from "old_transp_run"
and part from the Ufile/MDS+ specifications in the namelist.

The floating point quantities (old_transp_time) and (old_transp_stime)
refer to the time extent of the original run's input data.  The former
applies to plasma state data (temperatures, densities, total current);
the latter applies to data pertaining to heating and current drive 
sources (neutral beam powers, RF antenna powers, etc.).  These are
slightly different, because TRANSP's heating and current drive
calculation leads the transport calculation by a small amount, 
typically a few milliseconds.

By the methods described here, a "base run" for steering can be prepared 
and held in place, allowing many variant runs to reuse the run's results
for the "early part" of a discharge, saving computer time.

However, such runs cannot be preserved across code updates.  I.e. if 
the TRANSP code version changes, base runs will have to be re-executed.

4 ELVIS_output
TRANSP can generate limited numerical output which can be graphically
monitored during execution of the run.  To enable this, an ELVIS
graphics server must be available, and, the environment variable

  ELVIS_SERVER

must be defined to give the name of the server, on the machine where
TRANSP itself executes.

If these conditions are met, then, the following namelist controls
determine what quantities are to be output.  These controls use the
language of RPLOT, the traditional tool for the viewing of TRANSP
output (documented elsewhere).

  CHARACTER*128 RPLOT_PROG(20) -- RPLOT calculator script -- can
    contain a sequence of up to 20 RPLOT calculator commands which
    can be used to define additional outputs beyond what TRANSP 
    itself defines.  This is optional; the default is that this
    script is empty.

  CHARACTER*30 RPLOT_ITEM(20) -- up to 20 names of RPLOT items:
    the following types of RPLOT objects can be named:
      -- scalar functions of time (example: "VSUR").
      -- multigraphs of scalar functions of time (example: "CPDIS").
      -- profile functions of time & addl. coordinate (example: "TE").
      -- multigraphs of profile functions of time. (example: "IEBAL").
    Additionally, profile multigraphs can have applied transformations,
    i.e. RPLOT_ITEM(j)="VOLINT(IEBAL)" means the j'th ELVIS display 
    will be the volume integrated ion power balance, in Watts.

If ELVIS_SERVER is defined and RPLOT_ITEM(...) is defaulted, then the
following scalar multigraph outputs will be provided:

    CPDIS -- cpu time usage with breakdown by code component.
    LBPOL -- li/2 + beta(poloidal) multigraph.
    XNEUT -- neutron emission multigraph.

If RPLOT_ITEM(1)="NONE", then, the whole feature is suppressed
regardless of the availability of ELVIS_SERVER.

If ELVIS_SERVER is given a name starting with '/' or '.', then it is
interpreted as the name of a directory and instead of transmitting
the data to a server, the data will be written to the file
${ELVIS_SERVER}<runid>_<tok>.gw.

Elvis output data is generated at the same time as the rplot data.  The
Elvis data will be sent to the ELVIS_SERVER no more frequently then
every SEEDIT cpu seconds (default 15).  If SEEDIT<=0., the Elvis data 
is not sent to the server.

4 ACFILE_output
[New DMC 6 Dec 1991]

TRANSP has a new output facility -- Ascii Compressed files or ACFILES.

This facility may be used to select a few special times and output
any part or all of TRANSP COMMON to a file in a convenient portable
compressed ascii format.

Details concerning this facility are given in the separate document
source/doc/acfile.doc (also on the ftp server).

The following is a summary of ACFILE-related TRANSP namelist controls:

Character variables:
  SELOUT=' ... '  -- list of names of TRANSP COMMON symbols to output.
    If defaulted, ALL OF TRANSP COMMON is output (usually this is best).
  SELAVG=' ... ' -- list of names (REAL variables and arrays only) to
    average prior to output.  Must be a subset of SELOUT.  If 
    defaulted, nothing is averaged before output.
    For example:
         selavg='FBM BMVOL BDENS2 EBA2PL EBA2PP' 
    selects a basic set of data for fast ion distribution functions.
  OUTTIM=1.5,1.7,1.9, ... -- list in ASCENDING ORDER of times when
    ACFILEs should be written.  A maximum of 9 times may be given.
    If fewer than 9 times are given, fewer than 9 ACFILEs will be
    written.  The ACFILEs are named e.g. for run 12345A01:
        12345A01.DATA1  --  at OUTTIM(1),
        12345A02.DATA2  --  at OUTTIM(2), ... etc.
The following are relevant if SELAVG is non-empty:
  AVGTIM=averaging time, seconds -- for the jth output ACFILE, data
    that is averaged is averaged over the time range OUTTIM(j)-AVGTIM
    to OUTTIM(j).  NOTE -- OUTTIM(j) and OUTTIM(j+1) must be separated
    by at least AVGTIM seconds!  (Only one average can be accumulated
    at a time).
  MTHDAVG=averaging method.  set MTHDAVG=1 for default (use heating
    source timestep if available); MTHDAVG=2 to sample on completion 
    of each heating source timestep; MTHDAVG=3 to use a sampling period.
    Recommendation: use the default, MTHDAVG=1.
  AVGSAMP=sampling period, seconds.  If MTHDAVG=3 and the time is in
    range for averaging data for the next ACFILE, and if AVGSAMP or
    more time has passed since the last time point was averaged, then
    the next time point is averaged.  The effective sampling rate will
    be longer than AVGSAMP by of order 1/2 a TRANSP energy balance
    timestep.

4 Fast_Ion_Model_Test_Data
[New DMC 15 Apr 2003]

...This is a debugging feature.

At up to 9 user selected times, data may be saved to allow the modular
fast ion codes to be run in standalone mode.  Sufficient data is saved
to allow bit-for-bit reproduction of a fast ion calculation done at a
particular time in TRANSP, if the standalone code is run in a machine 
which is binary compatible with the machine on which TRANSP itself ran 
when producing the data.  If the standalone code runs on a machine 
which is not binary-compatible, the standalone rerun will not be 
identical bit it will be "very close" to the original.

The saved data is a unix archive (tar file) compressed with gzip.  
Therefore, the data can only be unpacked on a unix machine which
supports tar and gzip.  The contents will depend on what fast ion
models are present in the TRANSP run.  Generally, the contents will
consist in namelists (to drive the modules), NetCDF-based module
state files, and a NetCDF-based xplasma state file containing the
MHD geometry and various plasma parameters.  Unix-TRANSP includes
a script, codesys/csh/fi_gzn_unpack, to unpack this data.

The output times are specified in the namelist variable FI_OUTTIM(...):

  FI_OUTTIM(1) gives the time at which to write <runid>_FI_TAR.GZ1
  FI_OUTTIM(2) gives the time at which to write <runid>_FI_TAR.GZ2
     ...
  FI_OUTTIM(n) gives the time at which to write <runid>_FI_TAR.GZn

  (1 <= n <= 9).

Logical:
  
  NLNBI_TEST_OUT = .TRUE.   ! Default - .TRUE. for allowing write extra data 
			    ! in <RUNID>_fi directory for post facto debugging.
			    ! Set .FALSE. to suppress output of interim state
                            ! data for nubeam_test time step debug, rerun capability
                            ! (suppress e.g. to optimize NUBEAM mpi scaling).		
		            ! But if fi_outtim is/are  set, then NLNBI_TEST_OUT
   			    ! will be forced to be .TRUE. for this time step/s only.
                            ! see trfpi/nubeam_component_step.f90

Codes that can be driven by this data

  xfpprf -- standalone Fokker Planck code with attached RF full
            wave solvers.  (Assuming TRANSP itself was using the
            Fokker Planck package).

  nubeam_test -- standalone test driver for NUBEAM, Monte Carlo
            fast ion code (for beam- and fusion product ions).
            (Assuming TRANSP itself was using the Monte Carlo 
            package). This test can be used for debugging 
            MPI NUBEAM on a given sublist of particles (where
            crash appeared)

Note that `xfpprf' can also be run using standard TRANSP output data.
This avoids having to define the FI_OUTTIM(...) times of interest in
advance.  A TRANSP program, `gfpprf', is used to extract the xfpprf
driver namelist at the selected TRANSP time, and to specify where
(what file or MDS+ path) the TRANSP data is currently located.  The
`xfpprf' calculation driven in this manner is not bit-for-bit the
same as what was executed in TRANSP.  The Fokker Planck code's state
file (with beginning-of-timestep fast ion distribution function data)
is not available, and a Maxwellian distribution with the right
average energy is assumed instead.  Nevertheless, this is adequate
for many purposes, e.g. testing most RF wave codes.

5 fi_gzn_unpack_howto

"fi_gzn_unpack" is a csh shell script distributed with TRANSP and also
in the NTCC TRANSP tools module (tr_client).  To use it:

  a) go to a (preferably empty) working directory.
  b) copy the desired <runid>_FI_TAR.GZ<n> file to this directory.
  c) executate fi_gzn_unpack script with the filename as argument:

     fi_gzn_unpack <runid>_FI_TAR.GZ<n>

     (If you do not have access to fi_gzn_unpack script, you
      can use:

        tar xvfz <runid>_FI_TAR.GZ<n> )

  d) if the original TRANSP run used NUBEAM, the files needed to 
     execute the "nubeam_test" program have been unpacked.
  e) if the original TRANSP run used FPPMOD, the files to execute
     the "xfpprf" program have been unpacked.
  f) the filenames inside <runid>_FI_TAR.GZ1 and <runid>_FI_TAR.GZ2
     are the same, so use separate directories to look at both of
     these independently.

5 alternate_fppmod_test_data
Even if FI_OUTTIM(...) is not used (cf preceding section):  FPPMOD
namelists are saved N_FPWRNML times per TRANSP run.  These can be
retrieved by `gfpprf' and used in `xfpprf' to approximately reproduce
an ICRF/FPPMOD timestep, with extra plotting of wavefields, etc.  The
minority fast ion distribution function has not been saved, in this
mode; instead, the starting condition for the xfpprf timestep will be
a maxwellian at elevated average energy.

N_FPWRNML is a namelist control:

   default value:  100
   minimum value:   20
   maximum value: 2000

The N_FPWRNML output times are spaced evenly throughout a TRANSP run;
the associated namelist data is concatenated in an ascii file, 
<runid>FPPRF.DATA

4 SHOT_NUMBER
specify

NSHOT=nnnnn

in the namelist, where nnnnn is the "nominal" shot number of the
data to be analyzed in the TRANSP run.  This shot number is
"nominal" in the sense that the actual data may have been 
assembled from multiple shots.  The specification of NSHOT is
important because
  (a)  all UFILES read by TRANSP for this analysis must have the
shot number NSHOT imbedded in their filenames, and
  (b)  documentation.  The shot number NSHOT is associated with
the run's run number in TRANSP databases.
4 TRDAT_Namelist
TRDAT is used to acquire UFILE input data for TRANSP runs.  The
names of the input Ufiles and related controls are entered in
the TRDAT namelist.  These quantities are entered in the 
nnnnTR.DAT file between the records $TRDATA and $END.  Quantities 
between these two records are known as TRDAT namelist quantities;
all other quantities are TRANSP namelist quantities.  TRDAT 
namelist quantities are known to TRDAT but not to TRANSP; TRANSP 
namelist quantities are known to both TRDAT and TRANSP.  A handful
of TRANSP controls which specify handling of profile data are 
important to TRDAT and will be referred to in this section of 
TRANSPHELP.

5 UFILE_characteristics
This section added March 1992 -- new TRDAT installed.

The new TRDAT checks the units labels of input Ufiles.  UFILES ARE
NOT ACCEPTED UNLESS the Ufile units labels conform to the standard
defined by trdatgen.spec, the input file to the TRDAT code generator
TRDATGEN.  Instructions on how to find trdatgen.spec are in the
documentation section near the top of this file.

See also the description of the TRDAT namelist control LFIXUP.

General units conventions:

  all times are in SECONDS
  all distances are in CM
  ECE frequencies in GHZ
  Temperatures in eV, densities in CM**-3
  Surface voltage in VOLTS, plasma current in AMPS,
  .. etc ..

Some standard units conversions are also supported with LFIXUP=2,
e.g. KeV --> eV for temperature data (cf trdatgen.spec).

5 LFIXUP
The new TRDAT namelist switch LFIXUP is used to control units
conversion:

   LFIXUP = 0  ==> suppress all units conversion (if an unknown
                   units label is encountered a warning is printed).
                   This emulates the behaviour of the "old" TRDAT.
   LFIXUP = 1  ==> require labels to strictly follow TRANSP
                   conventions-- if unconventional labels are
                   detected, the input data is rejected.
                   LFIXUP=1 is the default value.
   LFIXUP = 2  ==> support conversion of data (e.g. multiply
                   data by 1000.0 to go from KeV to eV) and 
                   support axes swap if needed for profile data,
                   to satisfy the convention that "time" be the
                   "first" independent coordinate of the data.

mixed modes (added by dmc, Apr 1996):

   LFIXUP = 3  ==> as LFIXUP=0 but 2d Ufile time axes swap *is done*.
   LFIXUP = 4  ==> as LFIXUP=1 but 2d Ufile time axes swap *is done*.

LFIXUP=0 should be used only to allow old TRANSP runs to be
rerun, even if the input Ufiles units labels are incorrect.

The most restrictive option LFIXUP=1 is the default.

LFIXUP=2 is recommended.  HOWEVER, the units labels in your 
Ufiles must be correct!  This is a change from the old TRDAT,
which did not care what was in your Ufiles units labels!
If there are errors in the Ufiles units labels 
(e.g. the file says "KeV" but the data is actually in eV)
then the run could fail using the new TRDAT, even though the
old TRDAT would have accepted the data and TRANSP would have 
been happy-- because with LFIXUP=2, the new TRDAT will multiply
"KeV" data by 1000.0 to try to put it in "eV" for TRANSP.

LFIXUP=3 or LFIXUP=4 will be of use if it is desired to have
TRDAT standardize the axes ordering of input 2d Ufiles but
not convert units.
5 Scale factor
  ... added Jul 2007
A multiplicative scaling factor may now be defined for any input Ufile, 
using a namelist card SC_xxx. This changes the data values ( only ) -- 
independent coordinates (R or X) and time T are unchanged.
If a factor SC_xxx is supplied, then any error resulting from unknown 
Ufile units will be disregarded, on the assumption that the scale factor 
has been supplied to correct the error. It is the user's responsibility 
to ensure that this is in fact the case.
5 UFILE_names
  ... modif Aug 1986 -- see update note...
All input UFILEs for TRANSP runs reside in [TRANSP.<tok>.DATA] where
<tok> is the tokamak id.  The UFILE names all have the form
  <prefix>mmmmm.<extension>
where:
  <prefix> is an upto 16 character prefix specified in the TRDAT
namelist as CHARACTER*16 variable PRExxx,
  <extension> is an upto 16 character filename extension specified 
in the TRDAT namelist as CHARACTER*16 variable EXTxxx, 
  and xxx specifies the type of data to be contained in the named 
UFILE, and
  The SHOT NUMBER mmmmm is an integer of up to 6 digits length 
which is specified in the TRANSP (not TRDAT) namelist as variable 
NSHOT.

EXAMPLE:

NSHOT = 12345
$TRDATA
PRELID='S'
EXTLID='MWL'
$END

specifies S12345.MWL as input UFILE for the run.  The code "LID" in
the variable names indicates that the data type in the UFILE should
be "line integrated electron density" in units cm**-2

August 1986
UPDATE NOTE -- the TRDAT namelist controls INPUTDIR and INPUTDSK may
be set to override the source disk:[directory] for UFILES.  E.g. for
TFTR most ufiles are NOW stored in directories TR_DISK:[username] 
where username = the name of the physicist preparing the data.  Set 
INPUTDIR='username' in the namelist, and INPUTDSK='TR_DISK'.  The
default value for INPUTDSK is the TRANSP disk logical name TRHOME
(except at PPPL for TFTR runs only, TR_DISK is the default name).
6 CAUTION
Mere specification of an input UFILE for TRANSP usually does not
suffice to tell TRANSP "what to do" with the data.  It is usually
necessary to also set additional namelist switches to tell TRANSP
e.g. whether to use the data directly in modeling the plasma or
simply to pass it through to the plotting output file for comparison
with a simulation.
6 _1D_Data_types_partial_list
As of July 1985 the following 1D UFILES data types are recognized
by TRDAT and TRANSP as possible input files.  Set TRDAT namelist 
variables PRExxx and EXTxxx to request the data type for input.

ALL FILES ARE VS. TIME ONLY; TIME IN SECONDS ***

xxx   description                           units       notes
---   ------------------------------------  ----------  ----------
CUR   plasma current                        amps        A
VSF   loop voltage *at plasma surface*      volts       A
POS   plasma major radius                   cm          B
RMN   plasma minor radius                   cm          B
RBZ   external B field * major radius       tesla*cm    A,B
L2B   li/2+beta (Shafranov) vs. time        none        A,B
BDI   diamagnetic beta vs. time             none        A,B
DFL   diamagnetic flux vs. time             webers      A
LAD   line average density                  cm**-3      C
LID   line integral density                 cm**-2      C,D
FMN   minority ion fraction nmin/ne         none        T
TET   electron temperature (scalar data)    eV          E
TIT   ion temperature (scalar data)         eV          F
PFL   passive cx Ti lower fit limit         eV          F
PFL   passive cx Ti upper fit limit         eV          F
TXI   passive cx "intercept"                PDX units   ?
NTX   neutron production                    sec**-1     F
ZEF   Zeff (impurity parameter)             none        G
VSB   ctr chord Vis. Bremsstrahlung light   VB/cm**2    G
RCY   recycling ion source                  #/sec       H
TPI   ion particle confinement time         seconds     H
XKF   ion conduction parameter              none        J
VPH   plasma axial toroidal rotation        cm/sec      K
SAW   sawtooth event times                  sec         P

(In TRANSP the interpolation of this data to a specified time
is performed in subroutine PLPARM, datcor/plparm.for.  There
is a scalar TRANSP common variable for each data type)

In TRDAT the UFILES for the data are read.  The data is interpolated
to a standardized timebase which covers the TRANSP analysis time
range (TRANSP namelist quantities TINIT, FTIME).  The data is passed
to TRANSP via the ascii "unified physics file".

7 Sign_conventions
TRANSP has some expectations regarding the signs of f(t) input
signals.  TRDAT enforces these conventions where it can; other
conventions require user conformance.  The most important of these
f(t) sign conventions are as follows:

CUR (plasma current vs. time) is positive
    --The input data is multiplied by -1 to force this if necessary.

RBZ (R*Btoroidal in vacuum) is positive
    --The input data is multiplied by -1 to force this if necessary.
    --the RBZ sign multiplier XRNRBZ (+/-1) is saved for application 
      to DFL data (see below).

VSF (surface voltage) positive voltage is supposed to drive current
    in the direction of the main plasma current.
    --Since VSF changes sign, TRDAT makes no attempt to correct the
      sign.  The user needs to assure that the convention is followed.

DFL (displaced diamagnetic flux) positive means a paramagnetic plasma
    (Bphi increased over vacuum value); negative means a diamagnetic
    plasma (Bphi reduced from vacuum value).
    --The multiplicative factor XRNRBZ applied to force RBZ positive
      is **also** applied to the DFL data.
    --The user needs to assure that if the RBZ data is negative, then
      XRNRBZ*DFL (XRNRBZ = -1.0) fulfills the convention (positive => 
      paramagnetic plasma).

6 _2D_Data_types_partial_list
As of July 1985 the following 2D UFILES data types are recognized
by TRDAT and TRANSP as possible input files.  Set TRDAT namelist 
variables PRExxx and EXTxxx to request the data type for input.

There are several options for defining the spatial coordinate of 
profile input Ufiles-- see the section on Ufile_characteristics.

The filename of the TRANSP subroutine which does the final 
interpolation of the data is given.  TRDAT performs a preliminary
interpolation after reading the UFILE.

xxx  description                       units       notes  subroutine
---  --------------------------------- ----------  -----  ----------
NER  electron density profile data     cm**-3      C,L    PROFE.FOR
TER  electron temperature profiles     eV          E,L    PROFE.FOR
ECF  ECE electron temperature data     eV          E,L    PROFE.FOR
NMR  minority ion density profile data cm**-3      T,L    PROFE.FOR
BOL  bolometer/ power radiated data    Watts/cm3   M      RADX.FOR
ZF2  Zeff profile data                 none        G      GZEFF.FOR
VB2  Visible Bremsstrahlung profiles   VB/cm**3    G      GZEFF.FOR
TI2  ion temperature profiles          eV          Q,J    KAPAI.FOR
KI2  ion conductivity profiles         cm2/sec     Q,J    KAPAI.FOR
NB2  TFTR waveform neutral beam data   mixed.......R      NBPDAT.FOR
VP2  plasma rotation profile data      cm/sec      K      GOMEGA.FOR
OMG  plasma angular rotation data      rad/sec     K      GOMEGA.FOR
KE2  elec.conductivity profiles        cm2/sec     S      KAPAE.FOR
BPB  Field tilt Bp/Bt vs major radius  none        U      FBCALM.FOR
BPA  Field tilt a, tan(a)=Bp/BT, vs R  none        U      FBCALM.FOR

Note -- dmc 18 Sep 1998 -- the list is much longer now.  See
the specification file for a complete list:  trdatgen.spec --
described in the Documentation section at the top of the document.

6 Neutral_beam_data
As of summer 1986 most TFTR neutral beam shots are analyzed using a
special UFILE containing data vs time and "channel no." where each
channel specifies a power, or voltage, or energy fraction time trace
for a beam firing in the shot.  To use this method of inputting the
TFTR neutral beam data into TRANSP, the TFTR neutral beam waveform
data must be correct on the VAX.  Prepare a namelist for a TFTR 
TRANSP run in the area WORK:[TRANSP.TFTR].  Then run the program 
EXE:NBFILE.EXE and specify the run id.  Interactively specify use 
of waveforms; individual waveforms may be turned on and off if 
necessary.  NBFILE.EXE will create the NB2 UFILE containing the 
neutral beam data (including estimated energy fraction data). The
Namelist must contain geometry constants for all beams. Old-style
namelists must be converted with nblist. 

6 RF_heating_data
RF antenna powers (watts) vs. time and antenna number may be input
via the RFP 2d UFILE.  If the file is 1d, it is assumed that it 
there is only one antenna and the file contains the power on this
antenna as a function of time.

RF frequencies (Hz) vs. time and antenna number may be input
via the RFF 2d UFILE.  If the file is 1d, it is assumed that it 
there is only one antenna and the file contains the frequency
on this antenna as a function of time.

6 Moments_UFILES
There several flavors of "moments Ufiles" for specifying the 
evolution of the plasma boundary (or interior) geometry.

Set TRDAT namelist variables PRExxx and EXTxxx to request the data 
type for input.

TRANSP loads the boundary data via subroutine PLPARM (PLPRMF.FOR)
and the processing is handled via the GFRAM0/GFRAME subroutines
(see information under Code_Structure key).

Traditional (1980s) up-down SYMMETRIC boundary Ufile set:
xxx   description                           units   notes
---   ------------------------------------  -----   -----
RM0   0th R moment  vs. time only (1d)      cm      B,N
RMM   higher order R moments vs. time and
      moment number  (1d or 2d UFILE)       cm      B,N
YMM   higher order Y moments vs. time and
      moment number  (1d or 2d UFILE)       cm      B,N

Up-down ASYMMETRIC boundary Ufile set (a single 3d Ufile, usually
generated by TRANSP's `scruncher' program):

xxx   description                           units   notes
---   ------------------------------------  -----   -----
MRY   complete {R,Z} boundary moments set   cm

For LEVGEO=8, a complete moment-based equilibrium geometry is
specified as a 3d Ufile, produced by TRANSP's `scrunch2' program,
and TRANSP does not have to solve the MHD equilibrium:

xxx   description                           units   notes
---   ------------------------------------  -----   -----
MMX   all {R,Z} equilibrium moments         cm

  --OR (also available via `scrunch2' --

xxx   description                           units   notes
---   ------------------------------------  -----   -----
RFS   R(theta,x) of flux surfaces           cm       V
ZFS   Z(theta,x) of flux surfaces           cm       V

The set {RM0,RMM,YMM} is required by LEVGEO=5 (updown symmetric VMEC).
The updown asymmetric solvers (LEVGEO=6,7,9,10,...) can use any of the
above sets; if MMX is specified only the boundary moments are used; if
{RFS,ZFS} is used, boundary moments are derived from the x=1 (R,Z)
contour.

For LEVGEO=8, where the entire equilibrium is input, either the MMX 
file or the {RFS,ZFS} pair of files must be provided.

6 NOTES
NOTES referenced in the TRANSP input UFILE data type descriptions

  A - see TRANSP namelist info, re. MAGNETICS
  B - see TRANSP namelist info, re. GEOMETRY_LEVEL.  Major and
      Minor radii and beta, li/2+beta data valid for circular
      bdy geometry only (LEVGEO .LE. 2)
  C - see TRANSP namelist info re. ELECTRON_DENSITY
  D - line integral density is from an interferometer measurement
      of some sort.  If the wavelength of the interferometer is not
      specified in CM as scalar "LAMDA:" in the UFILE, it must be
      specified through the TRDAT namelist variable DLAMDA.
  E - see TRANSP namelist info re. ELECTRON_TEMPERATURE
  F - see TRANSP namelist info re. ION_TEMPERATURE
  G - see TRANSP namelist info re. PLASMA_COMPOSITION
  H - see TRANSP namelist info re. PTCL_BALANCE&neutrals
  J - see TRANSP namelist info re. ION_PWR_BALANCE (conduction)
  K - see TRANSP namelist info re. ROTATION
  L - if time dependent profile data is not available a 1d UFILE
      vs. position coordinate only may be substituted.  Then the
      profile shape is fixed for the duration of the TRANSP run.
  M - see TRANSP namelist info re. POWER_RADIATED.  A 1d UFILE
      vs. TIME may be used as a "wide angle" measurement.  A flat
      radiation profile shape will be assumed.
  N - 1d UFILES each contain single bdy R or Y moments vs. time.
      2d UFILES contain a sequence of either R or Y moments vs.
      time.  The 2d files must be organized time contiguous with
      order 1st, 2nd, ... nth moment.  Using 1d UFILES for the
      RMM and YMM inputs provides a convenient means of specifying
      a time evolving elliptical boundary.
...new Aug 1986...
  P - list of sawtooth event times as calculated by the pattern
      recognition code EXE:SAWTOO.EXE based on analysis of a trace 
      of ECE or x-ray data.  See namelist info re. SAWTOOTH_MODEL
  Q - Ti and/or conductivity *profile* data may now be accepted for
      *time and space* dependent setting of ion conductivity for the
      ion power balance.  See namelist info re. ION_PWR_BALANCE.
  R - TFTR only.  See special section on neutral beam data.
...new June 1987...
  S - Conductivity (thermal diffusivity) profile data may now be
      read from a UFILE, to be used to PREDICT the evolution of
      electron temperature.  Te measured (UFILE) input data is 
      still required (a) to provide initial and bdy conditions; 
      (b) for comparison to predicted result.  See ELEC_PWR_BALANCE
      options under description of the namelist.  Conductivity
      UFILEs may be extracted from TRANSP analysis runs using the 
      RPLOT program.  **Write such UFILES in ASCII to avoid loss 
      of data resolution to binary digitization/compression.
...new Feb 1989...
  T - see TRANSP namelist info re. MINORITY_ION_DENSITY
...new Jan 1990
  U - input of Ufile data containing Bp/Bt vs. t,R, i.e. the tangent
      of the angle of the field lines vs. time and midplane major
      radius, permits generation of a comparison with the result of
      the TRANSP poloidal field simulation -- see RPLOT profile
      multigraph.  The comparison will be aided if the Ufile data
      follows this sign convention:  Bp/Bt .gt. 0 if R.gt.Raxis,
      .le. 0 otherwise; Raxis = radius on midplane where Bp=0.
...dmc Jun 2009
  V - {RFS,ZFS} data give R(theta,x) and Z(theta,x); the theta range
      covered must be [0:2pi] or [-pi:pi]; the x range covered must be
      [0:1] where 0 refers to the magnetic axis (a singular surface,
      a single point repeated Ntheta times) and x=1 refers to the plasma 
      boundary.  The mapping (theta,x) <--> (R,Z) must be smooth and 
      fairly evenly spaced; a C2 spline interpolation must not result 
      in creation of additional singularities.

6 Complete_list_of_Ufiles
The TRDAT program has been rewritten to take advantage of the new
code generator TRDATGEN.  This makes it far easier to add new input
data types to TRANSP.

See section on documentation (misc/trdatgen.spec).
5 Time_series_Ufile_input
All data types, including time series data types, are identified
by three character "trigraphs".  For example, "CUR" is the 
trigraph for the time series data type giving the total plasma
current, amps, vs time.

For a given data type "XYZ", specify the TRDAT namelist quantities

  PREXYZ='<Ufile prefix>'
  EXTXYZ='<Ufile suffix>'

To set the prefix and suffix of the Ufile name.  If these quantities
are set, TRDAT will try to read and process the XYZ data using the
named Ufile (see section on Ufile_names for information on the
shot number and input disk and directory of the Ufile).  Although
TRDAT will read the data and make it available to TRANSP, this 
does not always guarantee TRANSP will use it.  Sometime an
additional switch needs to be set to tell TRANSP whether to use
the data or just pass it on to RPLOT for comparison to a model
calculation.

If the XYZ data is subject to discontinuous changes at sawtooth or
pellet events, see the sections on sawteeth, pellets, and 
event_handling.
5 Profile_Ufile_input
All data types, including profile data types, are identified
by three character "trigraphs".  For example, "NER" is the 
trigraph for the profile data type giving the plasma electron
density, ptcls/cm3, as a function of time and radius.

For a given data type "XYZ", specify the TRDAT namelist quantities

  PREXYZ='<Ufile prefix>'
  EXTXYZ='<Ufile suffix>'

To set the prefix and suffix of the Ufile name.  If these quantities
are set, TRDAT will try to read and process the XYZ data using the
named Ufile (see section on Ufile_names for information on the
shot number and input disk and directory of the Ufile).  Although
TRDAT will read the data and make it available to TRANSP, this 
does not always guarantee TRANSP will use it.  Sometime an
additional switch needs to be set to tell TRANSP whether to use
the data or just pass it on to RPLOT for comparison to a model
calculation.

If the XYZ data is subject to discontinuous changes at sawtooth or
pellet events, see the sections on sawteeth, pellets, and
event_handling.

Use of profile data requires specification of the spatial range
covered in the input Ufile (see "Range_specification").  TRDAT
checks that the data in fact covers the claimed range specification.
The severity of this check is determined by taking the minimum of
the "global" TRDAT control RMJCHK and the XYZ-specific control
XRCXYZ.  The default is RMJCHK=XRCXYZ=1.0 which sets TRDAT to
impose the most stringent requirement on coverage of plasma range.

Set 

   XRCXYZ = <a non-negative number less than one>

to reduce the stringency of the range coverage constraint and allow
greater extrapolation, for the XYZ data.  Set

   XRCXYZ = <a negative number>

to entirely suppress the range converage constraint for XYZ.

For more details see the subkey RANGE_CHECK.

Similarly, set RMJCHK to a number less than one to relax the range
coverage constraint for ALL TYPES OF PROFILE INPUT DATA.

Summary of TRANSP namelist impact of using profile data:

Whenever profile data is to be used, the range specification control
NRIxxx must be set.  If NRIxxx specifies two-sided symmetrizable
data, then the symmetrization control NSYxxx must also be set to
select the symmetrization algorithm.  See "Range_specification...".

The resolution (number of points) of the interpolation/extrapolation
of the data may be controlled by setting the control NXxxx, if for
some reason the default resolution is inadequate.  NOTE -- because
of the need for compatibility with old TRANSP namelists, sometimes
alternates to the name NXxxx are supported.  For example, for NER 
either namelist control NXNE0 or NXNER may be used to specify the
resolution of the interpolation of the NER (electron density) data.

List of supported nonstandard names as of April 1992:

   nonstandard name     standard name
   ================     =============
     NXNE0                NXNER
     NXTE0                NXTER
     NXZEF2               NXZF2
     NXNM0                NXNMR

Users are urged to use the standard names, but old namelists with
the old names will work OK.
6 Analytic_profile_options
(New DMC Nov. 2009)

It is now possible to specify profile inputs analytically, without Ufile
or MDS+ signal input required.

The analytic profile specification namelist data are updatable, so, time
dependence can be introduced by providing analytic profile coefficients
in repeated ~update_time blocks.

For each profile type xxx the following analytic profile controls are
available (default values are shown):

  n_analytic_form_xxx = analytic form (0)
    (if a value greater than 0 is set AND if no Ufile data is provided,
    then the profile is specified by analytic formula.  At present,
    values of 1 and 2 are supported; meanings given below).

  aprof_axis_value_xxx  -- axial value of profile (0.0)
  aprof_edge_value_xxx  -- edge value of profile (0.0)

  aprof_coeffs_xxx(1:8)  -- analytic profile coefficients
    (interpretation depends on setting of n_analytic_form_xxx).

  aprof_dt_transition_xxx  -- (updates only) time to transition from
    old profile specification to new profile specification.

As of Nov. 2009, 2 analytic profile forms are supported.  For notation
let:

  form = n_analytic_form_xxx

  F0 = aprof_axis_value_xxx
  F1 = aprof_edge_value_xxx

  alpha = aprof_coeffs_xxx(1)  ! form 1 or 2
  beta  = aprof_coeffs_xxx(2)  ! form 1 or 2
  gamma = aprof_coeffs_xxx(3)  ! used for form=2 only
    (aprof_coeffs_xxx(4:8) not currently used).

  x = radial flux coordinate, sqrt(normalized toroidal flux)

  form=1:

    profile f(x) = F1 + (F0-F1)*(1-x**alpha)**beta

    notes:  f(0) = F0; f(1) = F1; alpha > 0.0 and beta > 0.0 expected.

  form=2:

    profile f(x) = F0 + (F1-F0)*g(x)
                   g(x) = x**alpha*[1 + (beta-alpha)*(x**gamma - 1)/gamma]

    notes: alpha > 0.0 and gamma > 0.0 expected;
           f(0) = F0; f(1) = F1
           f'(0) = 0.0 if alpha > 1.0
           f'(1) = beta*(F1-F0)

Additional analytic forms will be added if requested by PTRANSP users.


Example of use (with updated values):

(main namelist)
  n_analytic_form_ner = 1
  aprof_axis_value_ner = 2.0e13
  aprof_edge_value_ner = 1.0e12
  aprof_coeffs_ner = 2.0,1.0    ! parabolic ne(x) profile

(update blocks @ end of namelist):

  ~update_time = 2.0
  aprof_axis_value_ner = 3.0e13
  aprof_dt_transition_ner = 1.0 ! transition, 2.0 -> 3.0s

  ~update_time = 3.0
  n_analytic_form_ner = 2
  aprof_axis_value_ner = 5.0e13
  aprof_edge_value_ner = 5.0e12
  aprof_coeffs_ner = 4.0,10.0,3.0
  aprof_dt_transition_ner = 0.1 ! transition, 3.0 -> 3.1s



5 Range_specification_for_profile_Ufiles
TRANSP accepts several "profile evolution" Ufiles, i.e. Ufiles
which give the time evolution of a profile measurement of a
plasma parameter.  Such Ufiles contain 2 independent coordinates,
one of which must be time.  The definition of the other coordinate
giving the spatial dependence is set by the namelist control NRIxxx
(where xxx is the TRANSP/TRDAT trigraph for the input data type).
The following options are available:

NRIxxx=1  -->  data vs. midplane major radius R covering range
               R0 to R0+a -- covering the "outer half" of the plasma
NRIxxx=-1 -->  data vs. normalized radius x=(R-R0)/a (0.0 to 1.0)
               covering the outer half of the plasma.
NRIxxx=2  -->  data vs. midplane major radius R covering range
               R0-a to R0+shift -- covering the "inner half" of the
               plasma, ideally allowing for outward shift of axis.
NRIxxx=-2 -->  data vs. normalized radius x=(R-R0)/a (-1.0 to 0.0)
               covering the inner half of the plasma.
NRIxxx=3  -->  data vs. midplane major radius R covering the whole
               plasma from R0-a to R0+a.
NRIxxx=-3 -->  data vs. normalized radius x=(R-R0)/a (-1.0 to +1.0)
               covering the both sides of the plasma.

if NRIxxx= +/- 3, NSYxxx must also be set to specify the
symmetrization algorithm-- see the section
  TRANSPHELP OPER NAMELIST DATA_SYMMETRIZATION

NRIxxx=4  -->  data vs. minor radius r covering range 0 to a.
NRIxxx=-4 -->  data vs. normalized minor radius r/a covering range
               0.0 to 1.0

*UPDATED* 7 Feb 2002 (DMC)
Flux coordinate options -- summary:

NRIxxx=+/-5 -> data x axis is SQRT(normalized TOROIDAL flux)
NRIxxx=+/-6 -> data x axis is normalized POLOIDAL flux
NRIxxx=+/-7 -> data x axis is SQRT(normalized POLOIDAL flux)
NRIxxx=+/-8 -> data x axis is normalized TOROIDAL flux

Details...

NRIxxx=5  -->  same as NRIxxx=-5
NRIxxx=-5 -->  data vs. flux coordinate xi = SQRT(tflux/tfluxbdy)
               where tflux = the toroidal flux enclosed by the 
               surface labeled by xi, and tfluxbdy is the total
               toroidal flux enclosed within the surface defining
               the plasma boundary.  xi is used internally in 
               TRANSP to label flux surfaces; xi ranges from 0
               (the magnetic axis) to 1 (the plasma boundary).

NRIxxx=6  -->  same as NRIxxx=-6
NRIxxx=-6 -->  data vs. flux coordanate psi = 
                 psipol/psipol(bdy) , where psipol = the
               poloidal flux enclosed within the surface, and
               psipol(bdy) the poloidal flux enclosed within the
               bounding surface; psi ranges from 0 to 1.

               caution:  points must be finely spaced near psi=0
               to get good spatial resolution near the magnetic
               axis.

NRIxxx=7  -->  same as NRIxxx=-7
NRIxxx=-7 -->  data vs. flux coordinate xpsi=SQRT(psipol/psipol(bdy)),
               where psipol = the poloidal flux enclosed within the 
               surface, and psipol(bdy) the poloidal flux enclosed 
               within the bounding surface; xpsi ranges from 0 to 1.


NRIxxx=8  -->  same as NRIxxx=-8
NRIxxx=-8 -->  data vs. flux coordinate psitor = tflux/tfluxbdy
               where tflux = the toroidal flux enclosed by the 
               surface, and tfluxbdy is the total toroidal flux
               enclosed within the surface defining the plasma 
               boundary.

               caution:  points must be finely spaced near psitor=0
               to get good spatial resolution near the magnetic
               axis.

(NOTE:  NRIxxx and NSYxxx go in the TRANSP namelist, not the
 TRDAT namelist -- this information is needed by TRANSP as well
 as TRDAT).

Note that in general TRANSP supports analysis of data with time
dependent geometry.  Input profile data must actually have the
claimed plasma coverage **at all times** in the analysis.  However,
if the data time range does not cover the analysis time range, 
TRDAT will extrapolate it in time flat along lines of constant 
x = (R-R0)/a.

If an input profile Ufile contains only one coordinate, this is
usually interpreted as requesting use of the same profile 
information at all times in the analysis.  (Exception:  bolometer
data and any other data for which /fallback_to_timeseries is set
in misc/trdatgen.spec).  CAUTION-- if time independent profile
Ufiles are used, then the plasma position or boundary should also
be time independent or at least nearly so.
               
6 RANGE_CHECK
TRDAT imposes range coverage requirements on input Ufile data,
depending on the Ufile range coverage specification control
NRIxxx.

The default is that the data must "come close" to covering the
specified range at all times in the analysis.  This requirement
can be relaxed by setting the TRDAT namelist input XRCxxx to a
number less than one; it can be turned off entirely by setting
the input XRCxxx to a number less than zero.

The following table gives coverage requirements for XRCxxx=1.0
and XRCxxx=0.0, in terms of the normalized major radius 
coordinate x = (R-R0)/a, where R0 and a are the plasma major
and minor radii defined on the plasma midplane:

          x=(R-R0)/a  x=(R-R0)/a          x=(R-R0)/a
NRIxxx    ideal       range requirement   range requirement
value     coverage    XRCxxx=1.0          XRCxxx=0.0
======    =========   =================   =================
 +/- 1     0 to +1     0.1 to 0.9          0.5 to  0.5
 +/- 2    -1 to axis  -0.9 to 0.0         -0.5 to -0.1
 +/- 3    -1 to +1    -0.9 to 0.9         -0.5 to  0.5
 +/- 4     0 to +1     0.2 to 0.9          0.5 to  0.5
 +/- 5  [not checked -- already mapped]
 +/- 6  [not checked.]

note that for NRIxxx=2, the data should ideally reach far 
enough over in radius to cover the magnetic axis; because
of "Shafranov Shift" this usually is a positive value of x.

The namelist default value of XRCxxx is 1.0.  For namelist
values of XRCxxx between 1.0 and 0.0, a cover requirement
intermediate to the ranges shown above is taken.

A global range check relaxation control RMJCHK is also
available, but its use is not recommended.

6 MY_NRI

(New DMC 19 Mar 2010) An input Ufile can now specify its own NRIxxx
value, through the value of the scalar data item "MY_NRI".  If this
scalar is present, its value overrides any namelist setting and becomes
the NRIxxx value for interpretation of the profile Ufile data.

If this scalar item is absent, then, the NRIxxx value must be set in
the namelist, as before.

5 Renormalization
These controls provide for profile data renormalization IN TRDAT.
All renormalizations default "off".

NLRNNE - set .TRUE. to renormalize density profile data IN TRDAT.
DLAMDA - line density interferometer wavelength, cm.  required if
         scalar "LAMDA:" is not in LID UFILE.
XDGLID - option to reduce or eliminate use of edge data (beyond
         nominal plasma bdy) in computing the ne renormalization.
         default:  any edge data provided is used, XDGLID=large.
         Set XDGLID=1.0 to prevent use of any profile data beyond
         r/a=1.0; set XDGLID=1.05 to prevent use of any data
         beyond r/a=1.05, etc.

NLRNTE - set .TRUE. to renormalize electron temperature profile data
         (TER) or (ECF) to scalar data (TET) in TRDAT.  Additional 
         control available via TRDAT namelist inputs XFRTE and 
         RMJRTE:
           RMJRTE = major radius location of time series data
                    being used to normalize the profile.  This
                    radius must be in the range of the profile
                    data and of the plasma.  If defaulted, the
                    peak value of the profile is renormalized
                    to match the time series data
           XFRTE  = renormalization adjustment.  XFRTE=1.0 by
                    default.  If TER is the profile data and
                    TET is the scalar data, then the factor of
                    renormalization is
                        ZNORM = 1 + [TET/TER(RMJRTE) - 1] * XFRTE
                    at each time; i.e. XFRTE=0.5 causes a 
                    renormalization to a data value half way
                    between the profile data and the renormal-
                    izing time series data; XFRTE=0.0 would be
                    a complicated way of turning off the
                    renormalization.

NLRNTI - set .TRUE. to renormalize the ion temperature profile data
         (TIR) to scalar data (TIT) in TRDAT.  Additional controls
         RMJRTI and XFRTI are defined analogously to RMJRTE and 
         XFRTE.

NLRNVP - set .TRUE. to renormalize the rotation profile data
         (VP2) to scalar data (VPH) in TRDAT.  Additional controls
         RMJRVP and XFRVP are defined analogously to RMJRTE and 
         XFRTE.  CAUTION-- since VPH and VP2 can be zero, an
         "additive" rather than multiplicative renormalization
         algorithm is attempted.  It is recommended that RMJRVP
         be set.  This option has not been extensively tested.
5 PELLETS
If a TRANSP run includes pellet injection then, for each pellet, a 
"hazard time interval" should be input to TRDAT to specify the time
range about the pellet injection time during which none of the UFILE
input data should be trusted.  TRDAT will extrapolate all UFILE data
forward/back to the pellet time(s) based on data values and time 
derivatives at the endpoints of the hazard interval(s)-- except as
modified, cf section on event_handling.

In the TRDAT namelist,
  TPELDA(1,J) = LAST VALID TIME for input UFILE data PRECEDING
                injection of the Jth PELLET.
  TPELDA(2,J) = FIRST VALID TIME for input UFILE data FOLLOWING
                injection of the Jth PELLET.

NOTES:
  1.  The time interval TPELDA(1,J) to TPELDA(2,J) must enclose an
      actual pellet event as specified in the TRANSP namelist.  See
      TRANSP namelist info on PELLETS.
  2.  The hazard intervals must be bounded away from the start and
      stop times of the TRANSP analysis (TRANSP namelist variables
      TINIT, FTIME).  These intervals may not overlap.
  3.  TPELDA controls do not have to be set for ablation simulations;
      they are only needed if there is an actual pellet event in the
      data.
5 Sawteeth
The TRANSP namelist switch DTSAWD specifies a data "safety interval"
of +/- DTSAWD seconds around each sawtooth event.  Except as modified
by explicit namelist control, Ufile data which falls within the
safety interval will not be used (if the Ufile is subject to event
discontinuities).  Data in this range will be extrapolated linearly
from surrounding data to the actual sawtooth event time, where
a discontinuity will be formed.  This is essentially the same
treatment as is given for pellet events.
5 Event_handling
TRDAT data types which in their definition in misc/trdatgen.spec
include the switch /event_discontinuity are subject to event
handling code which uses flat or linear extrapolation to enhance 
event discontinuities in the data.  
(See the sections PELLETS, SAWTEETH).

New *** you can change the time extrapolation method used for
events.  See the extrapolation subtopic.

The extrapolation windows are by default defined for all diagnostics
with the /event_discontuity characteristic; this includes mainly
all temperature, density, and Zeff related data.  For individual
event sensitive diagnostic data type ABC, the extrapolation window
may be INCREASED by setting

    XDTABC = <wider extrapolation window, seconds>.

This means that the ABC data within +/- XDTABC of any event is not
to be used, and that the event extrapolation is to cover this wider
range.

Event extrapolation can be disabled over several time ranges by
setting

    XTMABC = time1a,time2a, time1b,time2b, ...

Where the time ranges (time1a,time2a), etc., must be specified in
ascending order without overlap and time2a .gt. time1a is required.
All times are in seconds.
6 extrapolation
Default extrapolation forward/back to events from outside the 
event window is *linear*.

You can instead choose flat extrapolation, or some weighted
average between linear and flat.  The namelist controls for
this are in the TRDAT namelist.  There is one set of controls
for sawteeth events and one set for pellet events.  In each
set there is one global control that modifies the default
extrapolation for all diagnostics, and then there is a 
specialized control for each diagnostic which is subject
to event handling (i.e. temperatures, densities, Zeff
related information, neutrons, surface voltage).

Each control accepts a floating point number between
0.0 and 1.0.  1.0 means linear extrapolation, 0.0 means
flat extrapolation, something inbetween means something
inbetween extrapolation.

The TRDAT namelist controls are:

Pellets:

  XXTPEL (default 1.0) -- global control for all diagnostics.
  XTPaaa (default out of range) -- specific control for
    diagnostic aaa.  If defaulted or given a value not
    between 0.0 and 1.0 inclusive, the control is ignored
    and the global control is used for diagnostic aaa.

Sawteeth:

  XXTSAW (default 1.0) -- global control for all diagnostics.
  XTSaaa (default out of range) -- specific control for
    diagnostic aaa.  Works same as XTPaaa.

6 event_pathologies
If the run includes sawtooth or pellet events and extrapolation
is not disabled for a given data type ABC, then, the original Ufile
data that falls within the extrapolation windows bracketing events
is NEVER USED.  Extrapolation is based on "good" data that falls
outside event windows.  To do a normal linear extrapolation, there
must be at least two good data points between event windows.  If 
this condition is not satisfied, TRDAT will produce warnings and
a fallback extrapolation scheme will be used:

  * if there is one good data point, that data will apply between
    surrounding events with no time variation, creating step-
    function-like time dependence in the processed data.

  * if there are no good data points, data from before the preceding
    or from after the following event will be copied; there will
    be a discontinuity at only one of the (2 or more) events with
    no intervening valid data.  Pellet events will be selected
    over sawtooth events for "receiving" the discontinuity, but
    if there are multiple pellet events or no pellet events
    involved the discontinuity will be placed arbitrarily.

(A further elucidation is given in the comments to the TRDAT
subroutine trdatusub/setupel.for).

5 More_control_switches
These additional controls are available in the TRDAT namelist.

TIME0 Time of start of plasma (=0.0 normally, =40.0 for JET!)
       - this number is subtracted from the timebase of all 
         input Ufiles; TRANSP wants t=0.0 = time of start of 
         plasma.

XTEND  - distance (in normalized spatial coordinate x=(R-R0)/a )
         to extend the data beyond the plasma boundary.  The
         default is XTEND=0.05, which is normally adequate.

PCURI  - input fixed plasma current (amps).  If no UFILE available.
VSURI  - input fixed surface voltage (volts).  If no UFILE available.

TLIM1 -- ignore all Ufile data before time t=TLIM1.  The data at
         t=TLIM1 is extrapolated back flat in time.

TLIM2 -- ignore all Ufile data after time t=TLIM2.  The data at
         t=TLIM2 is extrapolated forward flat in time.

5 CONVERSION_of_old_NAMELIST
In March 1992 a new TRDAT was installed.  The new TRDAT namelist is
NOT STRICTLY COMPATIBLE with the old namelist; some anachronisms
have been cleaned up.

Therefore, if an old TRANSP namelist is to be re-used it will have
to be converted first!

This conversion can usually be done automatically using the program

   EXE:FIXNL.EXE

just run this program in the directory in which the faulty namelist
resides and give the run id imbedded in the namelist filename.

If FIXNL cannot fix the namelist, consult D. McCune for help.

At non-PPPL sites, the new TRDAT and FIXNL arrived with the
February 1994 release of TRANSP.
5 Expert_Module_Copy
(New June 1999)

You can specify a (non-default) source for the TRANSP run's
expert module ("SUBROUTINE EXPERT") by setting the trdat namelist
variable

   expert_file

to a string containing the full path to the desired source file.
This causes a copy from the indicated source file that overwrites
any pre-existing <runid>EX.FOR file.  The write is done when TRDAT
writes its physics data output file.

NOTE -- expert files contain subroutines that modify TRANSP operation.
It is not easy to get these to do so correctly; if in doubt seek help
from a TRANSP expert.

NOTE ALSO -- in March 2005, the TRANSP code switched from a COMMON-
based internal communications mechanism "include 'TRCOM'" to a
fortran-90 based equivalent mechanism "use trcom".  EXPERT modules
written in the old style will not work.

5 MDSplus

TRANSP input can also be specified by reference to a properly prepared
MDSplus TRANSP input tree.

  ** this section to be updated (dmcApr16) **

5 General_observations

The following general observations about TRANSP coordinates and 
mapping options of profile input data were written in response to
a query from the JET group -- D. McCune 24 Sep 2003.

  (a) the internal TRANSP radial coordinate "XI" is sqrt(Phi/Philim)
      where Phi is the toroidal flux enclosed within a surface, and
      Philim the toroidal flux enclosed within the boundary.

  (b) The X and XB (seen in the TRANSP output and e.g. by the "rplot"
      program that comes with TRANSP for looking at output data) is
      also sqrt(Phi/Philim).

  (c) TRANSP has a front end program, "trdat", which reads in data 
      signals-- the measured input data for the TRANSP run.

  (d) The trdat program does NOT use sqrt(Phi/Philim), because, it
      does not have an MHD equilibrium available to it.  However, TRANSP
      is a "prescribed boundary" code, and so, TRDAT does know the boundary
      of the outermost flux surface.  Accordingly, it defines a midplane 
      mapping coordinate defined in terms of major radii and the boundary
      surface half-width:

            x_trdat(R_mp) = (R_mp-R0_mp)/a_mp

      where

            R0_mp = (R_outer + R_inner)/2
             a_mp = (R_outer - R_inner)/2

            R_outer = outer (large R) midplane intercept of outermost
                      flux surface (the bdy)
            R_inner = inner (small R) midplane intercept of outermost
                      flux surface (the bdy)

      
      are all functions of the time varying prescribed plasma boundary
      contour.  x_trdat, by definition, covers the fixed range [-1,1].

  (e) There are a variety of options for specifying the spatial coordinate
      of TRANSP profile input data (NRIxxx namelist options for profile
      xxx), as described in the TRANSP help.  Several of these indicate
      variation against major radius (R_mp) with stipulation of coverage
      of either the inside half, outside half, or both sides of the plasma
      column.  Such profiles are mapped by trdat to x_trdat.  Subsequently
      inside TRANSP, when the full MHD equilibrium is known, these are
      mapped to XI flux surfaces; two-sided data is "symmetrized" by 
      one of two namelist selectable algorithms.

  (f) TRANSP profile input data can also be given as functions of normalized
      sqrt-toroidal or poloidal flux.  For such data, x_trdat is not used.
      The profile's flux grid is passed directly to TRANSP, and then 
      interpolated to the TRANSP grid (evenly spaced in sqrt-toroidal flux,
      not evenly spaced and with internal time variation in poloidal flux).

  (g) A special mapping for ECE electron temperature data allows these
      profiles to be specified directly as functions of EC frequency.
      This allows the mapping to flux surface to be deferred until the
      MHD equilibrium and field are known.


4 MHD_Geometry

TRANSP supports several levels of plasma (MHD flux surface)
geometry.  The selection is made via namelist integer switch
LEVGEO.  The supported levels are:

DMC Jan 2003 -- LEVGEO=0 & LEVGEO=1 are no longer supported!

LEVGEO=0:  simplest model.  Plasma flux surfaces are taken as
concentric toroids of circular cross section, with the major and
minor radius of the outermost surface fixed in time (specify via
namelist inputs RMINOR and RMAJOR, or specify UFILEs inputs of
major and minor radius vs. time which will be time averaged--
time variation ignored).  Specify the toroidal field by setting
namelist quantity BZ = external toroidal field (tesla) at RMAJOR.

LEVGEO=1:  geometry as in LEVGEO=0, except that major and minor
radius of outermost surface, and toroidal field, are functions of
time.  UFILEs are needed for:  major and minor radius vs time;
external field vs. time specified in form R*Btoroidal, Tesla*cm.

LEVGEO=2:  boundary as in LEVGEO=1 (same UFILEs data required), 
but a Shafranov style MHD calculation is done to estimate the
shift of interior (assumed circular) surfaces relative to the 
outer surface.  This shift information is then used in the 
throughout the code.  Note that the surface cross-sections 
are still circular.

LEVGEO=3:  [no longer available.]  The original version of VMEC
(c.f. LEVGEO=5, below) ... known as EQ2D.  These runs now use
LEVGEO=5.

LEVGEO=4:  [no longer available.] LEVGEO=4 runs now use VMEC
(LEVGEO=5).  This option used to invoke the VMOMS equilibrium
solver (1987).

LEVGEO=5: The plasma boundary may be non circular and is input in
"scrunched" Fourier moments form as time dependent UFILEs
("scrunching" indicates a particular theta parametrization for
the moments expansion. For PBX the "scrunching" is done in
program [TRANSP.PBX.DATA]MOMGET.). The external field is input as
with LEVGEO=1 or 2.  The internal plasma geometry is generated
with a full 2d MHD equilibrium calculation.

LEVGEO=6: The plasma boundary may be non circular <AND> up-down
asymmetric (e.g., JET, DIII-D, etc.). It is input in "scrunched"
Fourier moments form as a single time dependent 3D UFILE.
"Scrunching" indicates a particular optimal theta parametrization
for the moments expansion. It is obtained by running
SCRUNCHER.. The external field is input as with LEVGEO=1 or 2.  The
internal plasma geometry is generated with a full 2d MHD
equilibrium calculation.

LEVGEO=7: This option has been indefinitely disabled as of 26Mar2008
and will force LEVGEO=11 (TEQ) to be used instead. [The ESC code 
(Leonid Zakharov, Alex Pletzer) -- see the subtopic.] 

LEVGEO=8: *** The entire Equilibrium is input data from SCRUNCH2 ***

LEVGEO=9: The JSOLVER code -- see the subtopic.

LEVGEO=10: This option has been indefinitely disabled as of 26Mar2008
and will force LEVGEO=11 (TEQ) to be used instead. [The Rzsolver code 
(A Pletzer). Solves the Grad-Shafranov equation in (R,Z) coordinates. 
Also invoked in rescue mode when Esc (LEVGEO=7) fails to converge. 
Rzsolver may not be available on all sites; the code has some external 
dependencies  (Python modules) that don't ship with Transp. See 
rzsolver.doc for installation notes.]

LEVGEO=11: TEQ from Larence Livermore National Laboratory

LEVGEO=12: ISolver free boundary code running in prescribed boundary mode.

Input data to these MHD solvers are:
  required:
     external field (UFILES data -- R*Bz) vs. time
     plasma boundary (UFILES data -- Fourier moments set) vs. time
  optional Ufiles:
     q profile (equiv. current profile) from the poloidal field solver.
     Pressure profile (or Beta) from kinetic data, fast ion modeling,
        and power balance calculations.

For LEVGEO=8, the Ufiles output by scrunch2, specifying the entire
equilibrium, are required.

Output data are:  a full metric solution to the MHD fixed
boundary problem, including interior flux surface locations, and
"g function" i.e. para/diamagnetic correction to the toroidal
field due to poloidal plasma current.

5 Additional Controls

NSCRUNCH_OPT-[INT] if set nonzero then the flux surfaces will be scrunched
so poloidal flux lines are separated by equal arc lengths. The number
of moments used internally (NMOM) will be reset to the maximal permissible
value.  Available for TEQ(LEVGEO=11).

5 EQ2D[LEVGEO=3]

This option corresponds to a very old version of VMEC which has
been superseded by the LEVGEO=5 version.

LEVGEO=3 runs are treated with LEVGEO=5.

5 VMOMS[LEVGEO=4]

VMOMS is no longer available in TRANSP.

LEVGEO=4 runs are treated with LEVGEO=5.

5 VMEC[LEVGEO=5]

This code (VMEC = Variational Moments Equilibrium Code) was
written by Steve Hirshman of ORNL. In its full glory it solves
the full 3-d mhd equilibrium equations for arbitrary geometry.
Dick Wieland and Steve Hirshman have truncated to a 2-d code
suitable for modeling tokamak geometries of arbitrary moment and
adapted it to TRANSP. Its description follows.

1. It is a fixed boundary code; the plasma boundary prescribed by a
   set of Fourier coefficients in R and Y. [Cf. Namelist inputs for
   specifying the RM0,RMM,and YMM ufile inputs, respectively.]
           
2. It works on an equi-spaced "s" grid, where "s" corresponds to the
   normalized toroidal flux. Note that this is different from the
   TRANSP "radial" grid, which corresponds to "xi", the square root of
   toroidal flux. This stretching of coordinates leads to greater
   radial resolution at the edge, which is an advantage for high beta
   plasmas where the q profile increases rapidly at the edge.

3. It uses the steepest descent method to find a force balance
   solution to the MHD equations.

4. It requires as input :
 	a> Fourier specification of the plasma boundary
     	b> enclosed toroidal flux
       	c> pressure profile p(s)
       	d> iota-bar profile i(s)
 Note that this implies that i(s), or q, is "conserved".

5. It can handle pressure anisotropies IN PRINCIPLE. The stand-alone
   version, which mimics a TRANSP-driven environment, has options for
   invoking the anisotropy. The version currently in TRANSP, however,
   is purely isotropic.

For references, cf.
   a> S.P.Hirshman and J.C.Whitson, PHYS.FLUIDS 26, 3553 (1983).
   b> S.P.Hirshman and H.K.Meier, PHYS.FLUIDS 28, 1387 (1985).
   c> S.P.Hirshman and D.K.Lee, COMP.PHYS.COMM. 39, 161 (1986).

7. Sources for TRANSP VMEC can be found in the TRANSP CMS library
   under Group VMEC_SRC. Sources for the Standalone version are
   under Group VMEC_STANDALONE.

There are a number of namelist variables that control various
aspects of its operation. They are described below. [#NYI# means
"not yet implemented"]. Default values, as defined in "port.for"
are shown in parentheses.
           
 VMCEXPF-[REAL]  TENSOR CODE- PRESSURE GOES LIKE 
                 BMOD**EXPF (1.0) #NYI#
 VMCFTOLA-[REAL(10)] CONVERGENCE ARRAY
  (1)   =>   RELATIVE CONVERGENCE OF FSQ   - FORCE BALANCE (1.E-9)
  (2)   =>   RELATIVE CONVERGENCE OF BETAP - BETA POLOIDAL (5.E-4)
  (3)   =>   RELATIVE CONVERGENCE OF R00   - MAGNETIC AXIS (5.E-4)
  (4)   =>   ( >0) RELATIVE CONVERGENCE OF IP - TOROIDAL CURRENT
             ( <0) ABSOLUTE CONVERGENCE WRT EXPIP          (1.E-3)
             "RELATIVE CONVERGENCE" MEANS HOW HAS THE
              PARTICULAR PARAMETER CHANGED SINCE THE
              LAST ITERATION
              "ABSOLUTE CONVERGENCE" MEANS HOW CLOSE IS THE
              CALCULATED VALUE TO THE VALUE OF IP AT THE
              TARGET TIME STEP?
              FOR DETAILS ON THE CONVERGENCE ALGORITHM,
                               CF. VMCCNVRG.FOR
 NVMCDATA-[INT][IN]   MODE OF OPERATION FLAG                   (1)
    =0 => RUN WITH NAMELIST INPUT (STANDALONE)
    =1 => USE TRANSP ISOTROPIC PRESSURE
    =2 => USE TRANSP ANISOTROPIC PRESSURE (#NYI)
 VMCANISO-[REAL][IN]  [NVMCDATA=1 ONLY]                        (1)
    =0 => PPERP=PPARL=PRES(S)  - ISOTROPIC
    >0 => SIMULATE ANISOTROPIC USING ISOTROPIC
          -PPAR= PRES(S)*(B/B0)**VMCANISO
          -PPERP=PPAR*(1.-VMCANISO)
NVMCNINT-[INT]      GRID SIZE FOR SOLVING INITIAL GUESS       (10)
NVMCITER-[INT(10)]  ITERATION LIMIT ARRAY
 (1) MAX # OF ITERATIONS ALLOWED IN INITIAL (GUESS) LOOP    (3000)
 (2) MAX # OF ITERATIONS ALLOWED IN MAIN (RESTART) LOOP     (5000)
 NVMCORDR-[INT]   [NVMCDATA=2 ONLY] 
                  ORDER OF P(BMOD) FIT (#NYI#) (1)
 NVMCSTEP-[INT]   NUMBER OF TIMESTEPS BETWEEN :          (100)
                          - CONVERGENCE TESTS
                          - PRINTOUTS
 VMCPEXP-[REAL]   EXPONENT IN THE <M> CRITERION ADDED TO FORCE (4.0)
                  BALANCE TO MINIMIZE FOURIER SPECTRUM
           
A WORD OR TWO HERE ABOUT THE WAY IN WHICH THE CONVERGENCE TESTS
ARE IMPLEMENTED. EXTENSIVE STANDALONE TESTS INDICATE THAT OF ALL
THE POSSIBLE METRICS TO SCAN IN TRYING TO ASCERTAIN THE DEGREE OF
CONVERGENCE (E.G., FORCE BALANCE(FSQ), BETA POLOIDAL(BETAP), THE
POSITION OF THE MAGETIC AXIS (R00), AND THE NET TOROIDAL
CURRENT(IP) ) IP IS BY FAR THE MOST SENSITIVE. THE USER CAN
REQUEST  IP CONVERGENCE IN A RELATIVE SENSE OR IN AN ABSOLUTE
SENSE, IN WHICH CASE COMPARISON IS MADE WITH THE TARGET IP. THIS
ABSOLUTE OPTION IS NOT RECOMMENDED. THE NATURE OF THE
BOOTSTRAPPING BETWEEN MAGDIF AND VMEC IS SUCH THAT THE TARGET IP
CANNOT ALWAYS BE SATISFIED. THE RELATIVE OPTION IS RECOMMENDED.
ALL THE ABOVE MENTIONED CONVERGENCE METRICS ARE TESTED BY AND-ING
THEM TOGETHER.

           
IF PROBLEMS OCCUR IN VMEC, SUCH AS AN INABILITY TO CONVERGE TO A
SOLUTION, THENAN ADJUSTMENT OF ONE OR MORE OF THE ABOVE NAMELIST
VARIABLES MAY BE NECESSARY. WHAT FOLLOWS IS A ROUGH GUIDE TO WHAT
YOU MIGHT TRY.

 1> TIGHTEN SOME OR ALL OF THE VMCFTOLA CONVERGENCE ELEMENTS.
 2> INCREASE THE NUMBER OF ITERATIONS IN THE NVMCITER ARRAY.

 IF PROBLEMS PERSIST, CONTACT a TRANSP expert.

5 VMEC6[LEVGEO=6]

This code (VMEC6 = Variational Moments Equilibrium Code) 
is a descendent of the earlier VMEC [Levgeo=5] code described
elsewhere. It has been modified by Steve Hirshman and Dick Wieland
to be able to handle up-down asymmetric plasmas, as well as the
more mundane up-down symmetric types. At a cost of about a factor of
 3 or 4 in CPU execution time of course. 

See VMEC[LEVGEO=5] for details on its operation. What's new or
different is presented below.

1. It requires as input :
 	a> Fourier specification of the plasma boundary
     	b> enclosed toroidal flux (Phi-tot) <and> Ip
       	c> pressure profile p(s)
       	d> iota-bar profile i(s)
Note that this implies that i(s), or q, is "conserved".

The Phi-tot is used as an initial guess in arriving at a solution
that conserves Ip, by varying Phi-tot.

There is a stand-alone version of VMEC6, called VMEC6SA, that can
run using RPLOT 2d ufiles as input. It can be a useful tool for
diagnosing convergence problems in a TRANSP run. More information
on how to setup the namelist file will appear here soon.

There are a number of namelist variables that control various
aspects of its operation. They are described below. [#NYI# means
"not yet implemented"]. Default values, as defined in "port.for",
are shown in parentheses.
           
 VM6FTOLA-[REAL(10)] CONVERGENCE ARRAY
  (1)   =>   RELATIVE CONVERGENCE OF THE FINE GRID FSQ - FORCE BALANCE (1.E-9)
  (5)   =>   RELATIVE CONVERGENCE OF THE COARSE GRID FSQ - FORCE BALANCE(1.E-6)
 ##NYI## THE FOLLOWING CONVERGENCE CONDITIONS ARE NOT YET IMPLEMENTED ...
  (2)   =>   RELATIVE CONVERGENCE OF BETAP - BETA POLOIDAL (5.E-4)
  (3)   =>   RELATIVE CONVERGENCE OF R00   - MAGNETIC AXIS (5.E-4)
  (4)   =>   ( >0) RELATIVE CONVERGENCE OF IP - TOROIDAL CURRENT
             ( <0) ABSOLUTE CONVERGENCE WRT EXPIP          (1.E-3)
             "RELATIVE CONVERGENCE" MEANS HOW HAS THE
              PARTICULAR PARAMETER CHANGED SINCE THE
              LAST ITERATION
              "ABSOLUTE CONVERGENCE" MEANS HOW CLOSE IS THE
              CALCULATED VALUE TO THE VALUE OF IP AT THE
              TARGET TIME STEP?
              FOR DETAILS ON THE CONVERGENCE ALGORITHM,
                               CF. VMCCNVRG.FOR
 NVM6NINT-[INT]      GRID SIZE TO USE IN THE COARSE GRID DESCENT       (11)
 NVM6NS2 -[INT]      GRID SIZE TO USE IN THE FINE GRID DESCENT         (31)
 NVM6ITER-[INT(10)]  ITERATION LIMIT ARRAY
 (1) MAX # OF ITERATIONS ALLOWED IN COARSE GRID DESCENT LOOP    (500)
 (2) MAX # OF ITERATIONS ALLOWED IN FINE GRID DESCENT LOOP      (2000)
 (9) NVM6NINT to use during STARTUP, or 0, or -1         (0)
 (10) NVM6NS2 to use during STARTUP, or 0, or -1         (0)

 for NVM6ITER(9) and NVM6ITER(10):
   (0 means use the same values as specified for non-startup)
   (-1 means use the code defaults:  11 & 31, during startup only)
   (positive values give the actual values to use during startup
    only; NVM6NINT and NVM6NS2 as given are used for non-startup).

 NVMCSTEP-[INT]   NUMBER OF TIMESTEPS BETWEEN :          (100)
                          - CONVERGENCE TESTS
                          - PRINTOUTS
 VMCPEXP-[REAL]   #NYI# 
                  EXPONENT IN THE <M> CRITERION ADDED TO FORCE (4.0)
                  BALANCE TO MINIMIZE FOURIER SPECTRUM
 NVM6NTH-[INT]    #NYI# POLOIDAL GRID SIZE
           
 IF PROBLEMS OCCUR IN VMEC, SUCH AS AN INABILITY TO CONVERGE TO A
 SOLUTION, THEN AN ADJUSTMENT OF ONE OR MORE OF THE ABOVE NAMELIST
 VARIABLES MAY BE NECESSARY. WHAT FOLLOWS IS A ROUGH GUIDE TO WHAT
 YOU MIGHT TRY.

 1> TIGHTEN SOME OR ALL OF THE VMCFTOLA CONVERGENCE ELEMENTS. 
    CHANGE VMCFTOLA[5] FROM 1E-9 TO 1E-11
 2> INCREASE THE NUMBER OF ITERATIONS IN THE NVMCITER ARRAY.

 IF PROBLEMS PERSIST, CONTACT a TRANSP expert.

5 Beta_Adjustment
BETA ADJUSTMENT.  TRANSP normalized pressure (beta) is by default 
based on kinetic data.  However, Beta is also (indirectly) measured
by magnetics systems and can be input to TRANSP via UFILES as 
measured "li/2+beta vs. time" or "diamagnetic beta vs time".  If 
magnetic and kinetic indicators of beta disagree, it may be desirable
to tie the Beta input to the MHD equilibrium calculations to the
magnetic rather than the kinetic data.  The following TRANSP namelist
options exist for this purpose:

XABFAC = anomalous multiplier to apply to Beta before passing it to
  the MHD equilibrium code (may be set directly in namelist

NLALAM = .TRUE. to adjust XABFAC as a function of time to make
  li/2+beta for MHD consistent with input magnetic data (lamda).

NLABDA = .TRUE. to adjust XABFAC as a function of time to make
  beta for MHD consistent with diamagnetic beta data.

XABMIN = minimum allowed XABFAC to constrain feedback adjustment
XABMAX = maximum allowed XABFAC to constrain feedback adjustment

ROTATION BETA ADJUSTMENT:  An additional anomaly factor

  XUPHIFAC

(default 1.0) can also be used to adjust just the beta
contribution due to plasma toroidal rotation.  For a discussion
see "beta.doc" at ftp://ftp.pppl.gov/pub/transp/codata/doc ...

5 ESC[LEVGEO=7]
This option has been indefinitely disabled as of 26Mar2008
and will force LEVGEO=11 (TEQ) to be used instead.

5 SCRUNCH2[LEVGEO=8]
(New dmc 14 Aug 2002)

TRANSP now has an option to receive its entire equilibrium from input
data, not computing an internal equilibrium at all.

The program "scrunch2" can extract a time evolving equilibrium via 
time dependent contouring analysis of EFIT results that have been
stored in a "standard EFIT MDSplus tree" such as are created in the
NSTX, Cmod and DIII-D experiments in the USA.

NEW DMC Apr 2004:  "scrunch2" can also extract and "smooth" the MHD
equilibrium evolution from a prior TRANSP run.  This can be a method
to remove or reduce d(geometry)/dt noise in the transport analysis.

Scrunch2 creates the following Ufiles (prefix and path user specified,
prefix = "C" and default filename extensions shown):

  _3d Ufile:

  Cnnnnn.MMX -- a 3d Ufile containing the full equilibrium evolution,
                in scaled Fourier Moments form.

    --OR--

  Cnnnnn.RFS -- a 3d Ufile, R(t,theta,x) -- explicit flux surface R
  Cnnnnn.ZFS -- a 3d Ufile, Z(t,theta,x) -- explicit flux surface Z

    (This representation avoids Fourier series truncation error).

  _2d Ufiles:

  Cnnnnn.QPR -- q(x,t): q profile.  Note x = sqrt(phi/philim)
    -->important! note x based on Toroidal flux, not Poloidal flux
  Cnnnnn.GRB -- g(x,t) = (R*Bt) Tesla*m or Tesla*cm (see below)
  Cnnnnn.PRS -- P(x,t) (Pressure profile), pascals

  _1d Ufiles:

  Cnnnnn.TRF -- total enclosed toroidal flux, Wb, vs. time.
  Cnnnnn.PLF -- total enclosed poloidal flux, Wb/rad, vs. time.

When "scrunch2" writes its data, it can write in "TRANSP" mode
(TRANSP units, profiles written time-contiguous), or in its
default "standard" mode which gives the data in MKS

---> "Standard" mode scrunch2 output can be read by TRANSP, but
only if the namelist specifies LFIXUP=2 for automatic units 
conversion and time axes swapping.  This is recommended, but
will cause problems for Ufile datasets which have units labeling
errors.

SCRUNCH2 results can be used in TRANSP runs with LEVGEO=6,7,8, or 9.
When LEVGEO=6,7, or 9, the VMEC6, ESC or JSOLVER equilibrium solvers
are used and the MMX aor {RFS,ZFS} data specifies the boundary, and the
GRB and PRS Ufiles are passed through for comparison.  A comparison of 
the Shafranof shift from TRANSP's internal equilibrium and the EFIT-
based MMX or {RFS,ZFS} equilibrium will be generated.  The QPR Ufile 
can either be passed through for comparison to results from the Poloidal 
Field Diffusion equation, or, the current profile can be set directly from
QPR.

By setting LEVGEO=8, one requests that TRANSP not compute an internal
equilibrium at all, but simply use the EFIT results.

Summary of namelist settings to use scrunch2 data:

TRANSP namelist:

  LEVGEO=8  ! to use MMX or {RFS,ZFS} for the equilibrium evolution.
            ! if MMX or {RFS,ZFS} are given but LEVGEO.ne.8, use the full
            ! equilibrium data just for the boundary.

  NRIQPR=5  ! profile inputs given vs. sqrt(phi/philim)
  NRIGRB=5  ! i.e. normalized sqrt(TOROIDAL flux)
  NRIPRS=5

  ! warning! some other programs write QPR data vs. POLOIDAL Flux
  ! NRIQPR=6 will give the WRONG RESULT if used with scrunch2 output.

TRDATA namelist:

  LFIXUP=2  ! needed to convert units of "standard" scrunch2 output.

  PREMMX,EXTMMX -- Ufile prefix & suffix of MMX data
                   ! MRY or RM0/RMM/YMM data must be turned off!
    --OR--
  PRERFS,EXTRFS -- Ufile of R(t,theta,x)   ! use either MMX or this
  PREZFS,EXTZFS -- Ufile of Z(t,theta,x)   ! pair, *not* both.

  PREQPR,EXTQPR -- (as before) Q profile Ufile pre/suffix
  PREGRB,EXTGRB -- (new) (R*Bt) profile Ufile pre/suffix
  PREPRS,EXTPRS -- (new) Pressure profile Ufile pre/suffix

  PRETRF,EXTTRF -- Total enclosed Toroidal flux vs. time (Ufile)
  PREPLF,EXTPLF -- Total enclosed Poloidal flux vs. time (Ufile)

    and optionally:

New options in "scrunch2" allow these quantities to be provided:

  PREPSI,EXTPSI -- PSI(t,R,Z) external field evolution from EFIT
                   Psi @ mag axis = 0 by convention

  PRELIM,EXTLIM -- limiter location from EFIT: time invariant
                   contour (R,Z) expressed as a Z vs. R Ufile.

  PREPF0,EXTPF0 -- Psi0(t) -- PSI(t,R,Z) + Psi0(t) regenererates
                   EFIT Psi = R*A_phi -- if PREPSI,EXTPSI are
                   specified as input to TRANSP than this data must
                   also be provided.  It is the flux difference 
                   from the tokamak machine axis to the plasma 
                   magnetic axis.

One final note:  TRANSP will evolve a somewhat different pressure
profile than was used by EFIT to prepare the MDSplus tree input 
for scrunch2.  Also, if the poloidal field diffusion equation is
used, TRANSP will have a different q profile, and in either case
TRANSP gets an internal g (R*Bt) profile from a surface averaged
Grad-Shafranov solution, which will be slightly different than
what EFIT used.  Therefore, with LEVGEO=8, TRANSP will definitely
have an equilibrium which is not entirely self-consistent.  While
this is generally OK for source/heating codes, it is not OK for
MHD stability codes (but then, TRANSP equilibria are usually not
good enough for these codes even with other LEVGEO options).  The
pass-through of g(x,t), q(x,t) and P(x,t) data and total flux
data from EFIT allows a fairly quick assessment of the magnitude
of deviation of the TRANSP profiles and total flux from the ones 
used by the EFIT analysis.

6 psi(R,Z) flux geometry -- NLPSIRZ_FLUX=.TRUE.

When LEVGEO=8 is used and psi(R,Z,t) input data is provided in the
PREPSI,EXTPSI ufile, then some additional analysis will be performed
to extract the location of the X points, axis point and the point which
bounds the plasma (X point on separatrix or limiter point).  The following
additional rplot outputs are available
  RPMHD,ZPMHD,PPMHD,APMHD -> R,Z,psi,psi_machine of X points, axis point and bounding point
  NBMHD -> -1 if lower diverted, +1 for upper diverted, 0 for limited
  FBDY  -> offset of prescribed boundary and internal analysis boundary
           from the separatrix
  PSIRZ -> psi(R,Z) defined on RGRID,ZGRID axis.  This output is suppressed
           if NLPSIRZ_OUT=.FALSE. (default .TRUE.)

If in addtion NLPSIRZ_FLUX=.TRUE., then the analysis of the psi(R,Z) data
will also return the flux surfaces to be used within TRANSP.  This overrides the
flux data in the MMX or RFS,ZFS ufiles though these ufiles (or POS,RMN,ZPL,TRF 
available from scrunch2) are still needed for use in mapping the input data.

NLPSIRZ_FLUX=.TRUE. is fundamentally different then using MMX,RFS,ZFS because
not only the geometry of the flux data is contained in psi(R,Z) but also the
enclosed poloidal flux.  To help reconcile this with TRANSP, the NPSIRZ_MODE
controls how the q,g=R*Btor profiles are used with the psi(R,Z) data analysis,

  NPSIRZ_MODE = 102  -> TRANSP's q profile is used with the psi(R,Z) data
                        which determines how the geometry is mapped back to
                        TRANSP's sqrt(toroidal flux) coordinate. (default)
  NPSIRZ_MODE = -102 -> The input Q profile data (QPR) will be used for the psi(R,Z) 
                        analysis so changes in TRANSP's q profile will not
                        affect the mapping of the geometry.  This is equivalent
                        to using MMX,RFS,ZFS.
  NPSIRZ_MODE = 103  -> The g=R*Btor profile is used along with the psi(R,Z) data
                        to deduce a q profile which is then used in mapping back the
                        flux geometry back to TRANSP.
  NPSIRZ_MODE = -103 -> The input g=R*Btor profile data (GRB) and Q profile data (QPR)
                        derives a g(psi) profile which is used along with the psi(R,Z) 
                        input data to deduce an equilibrium solution for TRANSP.  The
                        TRANSP pressure profile has no effect on the equilibrium solution.
                        The input g profile data is renormalized to match R*Btor_vacuum 
                        and is used in TRANSP.

  Suggested modes of running NLPSIRZ_FLUX=.TRUE.:
    NPSIRZ_MODE=103  -> Let TRANSP determine g=R*Btor from the pressure and <J.B>
    NLQMHD=.TRUE.       currents and let psi(R,Z) determine the associated q profile
                        which is then used within TRANSP.
    NPSIRZ_MODE=102  -> TRANSP's q profile is used for the psi(R,Z) analysis.  The plasma
    NLPCUR=.FALSE.      current can not be adjusted in this mode because changes to
                        the q profile, which are used to match the plasma current, will
                        also affect the mapping.  Note, rplot output PCUREQ gives the
                        plasma current associated with the psi(R,Z) data. 
    NPSIRZ_MODE=-102 -> Basically run as though using MMX,RFS,ZFS data except the geometry
                        is coming from the psi(R,Z) data.  The poloidal flux in TRANSP
                        will not be the same as psi(R,Z) but the flux surfaces will be the
                        same.
    NPSIRZ_MODE=-103 -> Use g=R*Btor input data to determine the q profile.  The equilibrium
    NLQMHD=.TRUE.       will not change with the pressure profile so there will
                        be a large Grad-Shafranov error unless the TRANSP pressure
                        profile is consistent with the psi(R,Z) and g inputs.

Additional outputs with NLPSIRZ_FLUX=.TRUE. are the normalized internal inductances
at the psi(R,Z) analysis boundary (LIF_1,LIF_3) and at the separatrix (LIS_1,LIS_3).
LIF_1,LIF_3 will typically be offset from TRANSP's LI_1, LI_3 due to differences in 
the plasma current between TRANSP and the psi(R,Z) analysis.  rplot's calculator should
show  LI as being very similar to (PCUREQ/PCUR)**2 * LIF.

5 JSOLVER[LEVGEO=9]

The fixed boundary MHD equilibrium code JSOLVER solves the
Grad-Shafranov equation in flux coordinates and takes the pressure
gradient p'(psi)*psimax  and the parallel current profiles R j// 
defined on a constant poloidal flux psi mesh as input profiles. The 
code was originally written by S. Jardin, C. Kessel, J. Menard, 
D. Monticello, J. DeLucia and others. More recently (1999), it has 
been made portable and dynamically allocatable, thus making it 
suitable for implementation into TRANSP. The present version in 
TRANSP has been imported from the National Transport Code 
Collaboration Library ( http://w3.pppl.gov/NTCC ).

JSOLVER uses the poloidal flux as radial coordinate. This choice
is particularly appropriate for high beta plasmas as the surfaces
end up highly packed on the outer edge where more resolution is
demanded. An interesting feature of JSOLVER is its ability to
double the mesh size after a predefined number of iterations. This
explains why JSOLVER's mesh size is always a power of two.

Note that TRANSP supplies the toroidal flux and the iota-bar (=1/q)
profiles to the equilibrium codes. In order to obtain a JSOLVER
equilibrium solution that is consistent with the TRANSP iota-bar
profile, JSOLVER is executed from within a loop where the geometry
and current are incrementally adjusted. This iterative procedure 
controlled by the NITJSO parameter appears to converge after 3-4
iterations for TFTR cases, 5-10 for JET cases but fails sometimes
to converge for NSTX. Note that the consistency error can be monitored
during a run and looks like:

>>jter= 1 Relative error in J//=    0.0600
>>jter= 2 Relative error in J//=    0.0354
>>jter= 3 Relative error in J//=    0.0155
>>jter= 4 Relative error in J//=    0.0090
>>jter= 5 Relative error in J//=    0.0090

A value of Relative error < 0.01 is usually OK.

The equilibrium resolution is determined by 2 parameters MNJSO and
NDOJSO such that both the numbers of radial and poloidal mesh nodes
are ~ 2**(MNJSO+NDOJSO). Here, 2**MNJSO denotes the initial grid
size during a cold equilibrium calculation (1st time through the NITJSO
loop), which is then doubled NDOJSO times. Consider MNJSO = 5 as a
minimum. For difficult cases or when accuracy is required NDSJO =1-2
usually helps. Values of MNJSO > 6 are not advisable. Since JSOLVER
allocates the dynamically the memory, there is no limit in NDOJSO
although every mesh doubling appears to slow down the code by a 
factor 5-6. The final accuracy is determined by TOLJSO, which, if 
negative, is halved every time the mesh is doubled. An additional 
parameter NIMJSO controls the number of internal iterations before
the metric is updated.


Namelist parameters

NITJSO -[INT]  NUMBER OF JSOLVER ITERATIONS (3)
MNJSO  -[INT]  JSOLVER RADIAL & POLOIDAL GRID SIZE ~ 2**MNJSO (6)
NDOJSO -[INT] JSOLVER NUMBER OF TIMES MESH SIZE IS DOUBLED (0)
TOLJSO -[REAL] TARGET ERROR TOLERANCE. (1.E-06)
NIMJSO -[INT]   JSOLVER MAX NUMBER OF INTERNAL ITERATIONS (11)

In summary, JSOLVER can be an attractive alternative to VMEC6 when full
control over the accuracy and resolution is required by the user.
Unfortunately the price to pay for higher accuracy is slow execution 
so that JSOLVER will probably not become a popular choice for large 
runs. Another deficiency of JSOLVER is its observed inability
to handle NSTX data, apparently due to poor or oscillatory convergence
in the NITJSO loop.  JSOLVER also appears to experience difficulties 
when the geometry presents a sharp X point, a problem intrinsic to 
JSOLVER's algorithm which relies on the alignment of ghost points 
outside the last surface.

--Alexander Pletzer, 7 Jan 2000

5 RZSOLVER [LEVGEO=10]
This option has been indefinitely disabled as of 26Mar2008
and will force LEVGEO=11 (TEQ) to be used instead.


5 TEQ [LEVGEO=11]

TEQ is the MHD equilibrium code used in the Corsica transport code from 
LLNL.  This LEVGEO option invokes the inverse solver of TEQ for a fixed
boundary solution using the pressure and q profiles as input.  The
vacuum R*Btor is used as a boundary condition.  After the initial startup,
TEQ is called in a loop which adjusts the q profile near the edge region
in order to match to the total plasma current. The following namelist options
are available for controling TEQ,

  NTEQ_STRETCH - set the distribution of TEQ radial points or 0 to use the default.
                 11 -> uniform
                 22 -> quadratic axis and edge
                -22 -> (sin(i*pi/2))**2; i=1,mpsi
                -21 -> stretch quadratic on axis
                -12 -> stretch quadratic at edge
                -32 -> cubic on axis, quadratic at edge
                -23 -> quadratic on axis, cubic at edge
                -33 -> cubic on axis and at edge
  NTEQ_NRHO - number of radial points to use internally to TEQ.  By default
              this is set to the larger of 71 and the 1.5*(number of TRANSP
              boundaries). LLNL suggests this should be in the 61-81 range.
  NTEQ_NTHETA - number of poloidal points to use in TEQ.  Default 127.
  NTEQ_CONFIG - there may be multiple TEQ data files which can be used for a given
                tokamak.  This options selects one of them though typically there
                is only one data file in which case this option is ignored.  
                The default is 0.  Nonzero values which are available,
                    tokamak      NTEQ_CONFIG
                     MAST          0 or 1       single null configuration
                     MAST            2          up/down symmetric double null configuration
  NTEQ_MODE   - selects the free parameters matched in the Grad-Shafranov 
                solution.  The default is NTEQ_MODE=5.
                 1  <J.B>,  plasma current
                 2     Q,   plasma current
                 3     F,   plasma current
                 4     Q,   edge F = vacuum R*Btor
                 5     Q,   edge F = vacuum R*Btor with a loop to match plasma current
                 6  <J.B>,  edge F = vacuum R*Btor
  TEQ_SMOOTH  - half-width in TRANSP's xi coordinate to use for smoothing 
                the profiles prior to use in TEQ.  If TEQ_SMOOTH<0 then use a half-width
                of |TEQ_SMOOTH|/max(NZONES,30)  (default -1.5)
  TEQ_AXSMOOTH - this applies smoothing near the axis using the formula
                    half-width = |TEQ_AXSMOOTH|*min(1, (ximax-xi)/(ximax-xicut)) 
                 where xi is TRANSP's sqrt(normalized toroidal flux) coordinate
                 and ximax = 2.*|TEQ_AXSMOOTH|, xicut=|TEQ_AXSMOOTH|.  
                 A TEQ_AXSMOOTH=0.15 was found to be needed for a D3D regression test. 
                 If TEQ_AXSMOOTH<0. then the pressure profile will be dehollowed before
                 smoothing by forcing the pressure profile to have the peak value
                 all the way to the axis.  The default is TEQ_AXSMOOTH=.05
  SOFTTEQ   - The average Grad-Shafranov error is checked after the TEQ execution
              and if it is larger then this value or HARD_GSERROR then it is 
              considered a failure. (default 0.3)

Useful rplot outputs when using the TEQ option
  GSERROR  - actual average Grad-Shafranov error.  This should be stunningly good
             when TEQ successfully runs.
  TEQRESID - The resdual computed by TEQ.  The target residual is 1.e-6.  If the
             actual residual is larger then 10. times the target, this output
             will be negative indicating a warning.  A residual 100. times larger
             then the target is considered a failure.
  IPCMP    - Multigraph comparing the plasma current as measured, used and implied by
             the equilibrium

There is some logic to abandon matching of the plasma current if the TEQ residual 
becomes too large (warning level -- see TEQRESID) and to switch from matching to
q to matching to current if there is a failure.  This logic along with the defaults
may be adjusted over time as experience with TEQ in TRANSP develops (May 2006).


5 Isolver [LEVGEO=12]

Isolver is a free boundary equilibrium code which was originally written in 
IDL by J. Menard. It has been rewritten in Fortran and installed in TRANSP.  
Isolver can be run in two modes:

  Least Squares: the poloidal field coil currents are adjusted in a least squares manner 
                 to match the prescribed boundary as input to TRANSP.

  Circuit Equation: measured coil current data along with feedback circuits are used
                    to solve the circuit equations for the poloidal field coil currents.
                    This is a work in progress.

6 Isolver Least Squares mode 
In this mode, the poloidal field coil currents are adjusted in a least squares manner 
to match the prescribed boundary as input to TRANSP through the MMX or RFS,ZFS ufiles.
The coil currents can be left unconstrained or can be constrained to experimental coil 
currents defined in a PFC ufile.  Least squares mode is the default mode when FB_NAMES 
has not been defined.  

The code tries to guess the location of the X points and will use them as part of the 
least squares solution.  The EQ_*_WEIGHT namelist options can be used to adjust the 
relative weighting to apply to the prescribed boundary, X point or coil currents but 
you probably won't need to change them.

The coil currents will typically have a poor correlation with the measured currents.  The
outside coils establish the vertical field so they will tend to have the best correlation.
The ohmic coils tend to be weakly coupled to the plasma shape and so may have wild values
or even be zero if the coupling is very small.  If measured coil currents are available,
I typically constrain the ohmic coil currents to the measured data using PFC_SIGMA(K)=-1
where K is the index of the ohmic coil.

6 Isolver Circuit Equation mode
In this mode, the poloidal field coil currents are based on a solution of the circuit
equations if any.  The measured coil currents must be input with the PFC_NAMES option.

Feedback circuits are used to position and possibly shape the plasma. The feedback 
circuits are specified with the FB_NAMES namelist switch which also turns on
circuit equation mode in Isolver.  Set FB_NAMES='None' to turn on circuit equation mode
with no feedback circuits (and good luck).  The only feedback circuits currently available 
are ideal current sources with names like 'iver' and  'ihor' -- see the 
"Isolver Tokamaks" section for more info,  
     FB_NAMES(1) = 'iver'   ! feedback circuit to position plasma vertically
     FB_NAMES(2) = 'ihor'   ! feedback circuit to position plasma horizontally

The prescribed boundary in TRANSP is used as a guide for positioning the plasma and 
so is still needed as input.  The prescribed boundary is also used in least squares mode 
during initialization before the run so it should be a reasonable representation of 
the plasma at the first time point.  The feedback circuits pick points on the prescribed
boundary to use for the feedback.  This is a work in progress so the options will be changing.

Notes:
  - When limited, the horizontal feedback needs to be increased so use
      FB_NAMES = 'iver','ihor'
      FB_LIM_FEEDBACK = -1., 20.  ! default feedback is typically 2.
  - The plasma shape can deviate significantly from the prescribed boundary.  Use
      XBDYCHK=0. 
    to prevent TRANSP from checking the deviation of the plasma boundary.
  - See NISO_QEDGE.  NISO_QEDGE=2 can sometimes interact poorly in circuit equation
    mode.  Consider using NISO_QEDGE=1 with NLMDIF=.T or .F or NISO_QEDGE=0 when
    using q data (NLMDIF=.F).  NISO_QEDGE=0 has the best convergence properties but
    don't use it with poloidal field diffusion.
  - To help the solution
     XISO_PCURQ_SMOOTH = -3 ! increased smoothing will affect the q match but help convergence
     NISO_NJPRE = -4        ! adds a 4 point interation filter to Jphi, helpful with high beta
     NISO_MAXITER = 300     ! circuit equation mode can converge more slowly (ugh!)

7 Isolver Circuit Equation Namelist Variables
These are only used in circuit equation mode (FB_NAMES defined)

  FB_NAMES(:) = list of the names of feedback circuits to use in the circuit equation mode.  
                You will need at least one vertical feedback circuit and one horizontal 
                feedback circuit -- usually 'iver' and 'ihor'.  Set FB_NAMES(1) to 'None'
                for no feedback circuits.  If this is not defined, you will run in
                least squares mode.

  FB_FEEDBACK(:) = normalized feedback for each of the FB_NAMES feedback circuits.  Set
                   a feedback <0 to use the default for the circuit. (default -1.)

  FB_FEEDOMEGA(:) = relaxation coefficient for FB_FEEDBACK or <0 for default (default 2.)

  FB_LIM_FEEDBACK(:) = this feedback overrides FB_FEEDBACK when the plasma is limited

  FB_ADV_SCALE(:) = apply this scale factor to the feedback when advancing time in isolver.
                    Primary use is to turn off feedback and (hopefully) let the vessel currents
                    control the position.

  PASS_NAMES(:) = when in circuit equation mode, this is an optional list of passive structures
                  to include in the equilibirum solution through coupling by induced current.  
                  This list can contain names of collections of passive structures identified
                  with a leading @ symbol.  The typical one to use is '@pass' for all of the 
                  passive structures if it exists for the tokamak.

  TINIT_PRECOIL = see section on "Isolver Vessel Currents", works with PASS_NAMES

  XISO_RELBAL   = in circuit equation mode, adjust the geometry time step to meet this
                  criteria for the relative circuit balance -- see WWRELBAL rplot output.  
                  Off by default but suggest XISO_RELBAL=1.e-4 if used.  Limited usefulness
                  when used with TRANSP's poloidal field diffusion.
  XISO_RELBAL_DT= do not allow the geometry time step to get below this value for the purpose 
                  of meeting XISO_RELBAL.  Should be larger than DTMING. (default 1.e-4)
  NEQ_REDO      = in circuit equation mode, maximum number of times a time step will
                  be redone to meet XISO_RELBAL or a flux diffusion criteria (default 4)

  NISO0_CIRC    = Index of geometry step during startup before NSTEP=1 (max steps is 5) 
                  when measured coil currents will start to be applied or 0 to 
                  begin applying the measured coil currents at NSTEP=1. (default 2)
         
7 Isolver Vessel Currents
Vessel currents may be included in circuit equation mode by setting the names of the
passive coils which make up the vessel (see PASS_NAMES).  Since there are so many
passive coils, you will usually just give the name of the main passive coil collection,
  PASS_NAMES = '@pass'

And for NSTX you would need to use the isolver configuration file which includes the 
passive coil definitions,
  ISO_CONFIG='pass'  ! NSTX ONLY!

By default, the vessel currents start off at zero at time TINIT.  However, a simulation 
of the effect of the poloidal field coil currents on the vessel before TINIT can
be made so that the TRANSP simulation starts off with realistic vessel currents.  You
must have PFC input data (and CUR input data when NLPCUR_PRECOIL=.TRUE.) for the
time range [TINIT_PRECOIL, TINIT],
  TINIT_PRECOIL - set this to simulate the induced currents in the vessel over the
                  time range [TINIT_PRECOIL, TINIT] (default, no simulation)
  DTMAXG_PRECOIL - default time step for pre TINIT simulation (default .005)
  DTMING_PRECOIL - minimum time step for pre TINIT simulation (default 1.e-4)
  RELBAL_PRECOIL - shorten the time step to meet this circuit balance.  There
                   is no error if this balance can not be met.  (default 1.e-4)
  NLPCUR_PRECOIL - .TRUE. to include the plasma current from [0.,TINIT_PRECOIL]
                   using a small coil at the plasma center. (default .TRUE.)
	
7 Isolver Circuit Equation Mode Outputs
   The following outputs are available in circuit equation mode (FB_NAMES defined).

   FBCURS   = current feedback circuit currents (multigraph of FC_<NAME>)
   FBVOLTS  = voltage feedback voltages (multigraph of FV_<NAME>)

   FC_<NAME> = current in current feedback circuit <NAME>
   FV_<NAME> = voltage associated with voltage feedback <NAME>

   WWFIELD  = power to coil fields from coil currents
   WWKKDPL  = power extracted from coil currents due to dplasma/dt
   WWRESIST = power dissipated in coil and source resistances
   WWSOURCE = power supplied by voltage/current sources
   WWBAL    = circuit power balance
   WWRELBAL = relative circuit power balance

   WWCIRC = multigraph of circuit powers

6 Isolver Tokamaks
Isolver requires a precomputed state file which depends on the geometry of the tokamak.  
As a result, Isolver can only be used for runs on the tokamaks listed below.  The names of 
the default set of poloidal field coils and of the available poloidal field coils as 
defined in the Isolver state file are listed for each tokamak.  Some of these
coils represent groups of other coils.  These coil names are needed for PFC_NAMES.

Also listed are the feedback circuits available for each tokamak.  The feedback circuits
position the plasma in the circuit equation mode.  Each feedback circuit has a predetermined
set of points on the prescribed boundary which are probed for the feedback and a set of coils
which are driven by the feedback.  The feedbacks are needed for FB_NAMES.  There is 
a common set of feedback circuit names used in each tokomak which only differ in the coils
used to control the feedback,
            'iver':    vertical position feedback using an ideal current source 
                         points: -90 and 90 degrees from centroid on boundary
            'iver3':   same as 'iver' except using points -80,-90,-100 and 80,90,100
            'ivermax': same as 'iver' except using points at boundary min,max Z
            'ihor':    horizontal position feedback using an ideal current source 
                         points: -20,0,20, and 160,180,200 degrees from centroid on boundary
            'ihor1':   same as 'ihor' except using points 0,180

  NSTX -- Configurations: ['orig', 'upgrade', 'pass']
          'orig' (default configuration) PF coils:
             pfc: ['oh', 'pf1al', 'pf1au', 'pf1b', 'pf2l', 'pf2u', 'pf3l', 'pf3u', 'pf5']
             all: pfc + ['pf4']
          'upgrade' PF coils:
             pfc: ['oh', 'pf1al', 'pf1a', 'pf1bl', 'pf1b', 'pf1cl', 'pf1c', 'pf2l', 'pf2', 
                   'pf3l', 'pf3', 'pf4', 'pf5']
          'pass' the PFC coils from the 'orig' configuration and the passive coils in the
                  '@pass' collection (81 of them).  The upper and lower primary and secondary
                   passive plates are each divided into four segments.  To model the poloidal
                   cut, three loop currents which do not cross the cut and with low 
                   resistance (e.g. uppp:a, uppp:b, uppp:c) are used with one loop current
                   with a higher resistance which crosses the cut (uppp:1).  This is done
                   for each of the passive plates uppp, uspp, lppp, lspp.
          Feedback Circuits
             'iver', 'iver3', 'ivermax':  standard vertical position feedback
                         coils:  +pf3l, -pf3u
             'ihor', 'ihor1':  standard horizontal position feedback
                         coils:  +pf5

  D3D -- PF coils
           pfc: ['f1a', 'f2a', 'f3a', 'f4a', 'f5a', 'f6a', 'f7a', 'f8a', 'f9a', 'f1b', 
                 'f2b', 'f3b', 'f4b', 'f5b', 'f6b', 'f7b', 'f8b', 'f9b', 'ecoila', 'ecoilb']
           all: ['e3_1', 'e3_2', 'e3_3', 'e4_1', 'e4_2', 'e4_3', 'e5_1', 'e5_2', 'e5_3', 'e5_4', 
                 'e5_5', 'e6_1', 'e6_2', 'e6_3', 'e6_4', 'e6_5', 'ein', 'eout', 'f1a', 'f2a', 
                 'f3a', 'f4a', 'f5a', 'f6a', 'f7a', 'f8a', 'f9a', 'f1b', 'f2b', 'f3b', 'f4b', 
                 'f5b', 'f6b', 'f7b', 'f8b', 'f9b','e1', 'e12', 'e2', 'e3', 'e4', 'e5', 'e6', 'eax', 
                 'ebx', 'ecoila', 'ecoilb']
           notes: the interlaced E1 and E2 coils with 48 turns each are not modeled -- instead 
                  the inner and outer branches of these ohmic coils are called ein,eout with
                  24 turns each.  e1=e2=e12 are defined as the series connected ein+eout and so
                  they each have 48 turns.  eax = ecoila without e1, ebx=ecoilb without e2. 
                  When using measured data in the PFC file, ecoila and ecoilb should be used for the
                  ohmic coils.
         Passive coils
           Defined in the '@pass' collection
         Feedback Circuits
            'iver', 'iver3', 'ivermax':  standard vertical position feedback
                         coils: +f7a,-f7b
            'ihor', 'ihor1':  standard horizontal position feedback
                         coils: +f6a,+f6b

  ITER -- PF coils
           pfc: ['cs3u', 'cs2u', 'cs1u', 'cs1l', 'cs2l', 'cs3l', 
                 'pf1', 'pf2', 'pf3', 'pf4', 'pf5', 'pf6']
           all: ['cs1l', 'cs1u', 'cs2l', 'cs2u', 'cs3l', 'cs3u', 
                 'pf1', 'pf2', 'pf3', 'pf4', 'pf5', 'pf6', 'pf6_01', 'pf6_08', 'pf6op3']
           notes: pf6 = pf6_08 -> baseline 2008 pf6
                  pf6_01 -> baseline 2001 pf6
                  pf6op3 -> option 3 pf6
          Feedback Circuits
            'iver', 'iver3', 'ivermax':  standard vertical position feedback
                         coils: +pf1,+pf2,-pf6,-pf5
            'iver16': same as 'iver' but using different coils
                         coils: +pf1,-pf6
            'ihor', 'ihor1':  standard horizontal position feedback
                         coils: +pf3,+pf4

  MAST -- PF coils
           pfc: ['p1', 'p2a', 'p2b', 'p3a', 'p3b', 'p4a', 'p4b', 'p5a', 'p5b', 'p6a', 'p6b']
           all: ['p1', 'p2ai', 'p2ao', 'p2bi', 'p2bo', 'p3a', 'p3b', 'p4a', 'p4b', 'p5a', 'p5b', 
                 'p6al', 'p6au', 'p6bl', 'p6bu', 'p2a', 'p2b', 'p6a', 'p6b']
           notes: coil geometry based on Cox, Fusion Eng. Design, 46 (1999) 397-404 
                  and some eyeball guessing (any MAST folks with better data?)
          Feedback Circuits
            'iver', 'iver3', 'ivermax':  standard vertical position feedback
                         coils: +p6b,-p6a
            'ihor', 'ihor1':  standard horizontal position feedback
                         coils: +p4a,+p5a,+p5b,+p4b
          
  EAST -- PF coils
           pfc: ['pf1', 'pf3', 'pf5', 'pf7', 'pf9',  'pf11', 'pf13', 
                 'pf2', 'pf4', 'pf6', 'pf8', 'pf10', 'pf12', 'pf14']
           all: <same>
          Feedback Circuits
            'iver', 'iver1', 'ivermax':  standard vertical position feedback
                         coils: +pf11,-pf12
            'ihor', 'ihor1':  standard horizontal position feedback
                         coils: +pf13,+pf14
          
  CMOD -- PF coils
           pfc: ['oh1',  'oh2u', 'oh2l', 'ef1u', 'ef1l', 'ef2u', 'ef2l', 
                 'ef3u', 'ef3l', 'ef4u', 'ef4l', 'efcu', 'efcl'])
           all: <same>
           notes: coil and limiter data was scrounged from the internet and so
                  is probably not quite right.
          Feedback Circuits
            'iver', 'iver3', 'ivermax':  standard vertical position feedback
                         coils: +efcu,-efcl
            'ihor', 'ihor1':  standard horizontal position feedback
                         coils: +ef4u,+ef4l

  IGTR -- Ignitor PF coils
           pfc: ['p1', 'p2', 'p4', 'p6', 'p8', 'p9', 'p10', 'p11', 'p12', 'p13', 'p14', 'p15', 
                 'm1', 'm2', 'm4', 'm6', 'm8', 'm9', 'm10', 'm11', 'm12', 'm13', 'm14', 'm15']
           all: <same>
          Feedback Circuits
            'iver':  standard vertical position feedback
                         coils: +p11,-m11
            'ihor':  standard horizontal position feedback
                         coils: +p14,+m14
          

6 General Isolver Namelist Variables and Inputs
The following namelist controls are available:

  NLPFC_CIRCUIT = the poloidal field coil currents as input throught the PFC ufile can be 
                  defined as circuit currents (Amperes) or as total poloidal coil
                  current (Ampere-turns)
                   .TRUE.  -> PFC currents are circuit currents (A)
                   .FALSE. -> PFC currents are total currents (A-turns) (default)

  PFC_NAMES(:) = optional array containing the names of the poloidal field coils to use
                 in the solution.  If not present then the default set of coils 
                 will be used and the coil currents will be unconstrained.  This array
                 is required if PFC ufile data is input.  The names must exactly match
                 the coil names in the Isolver state file as listed above.

  PFC_SIGMA(:) = if PFC_NAMES is defined and there is a PFC ufile containing experimental
                 coil currents then this is an optional array of real numbers which
                 describes how to adjust the coil currents in the equilibrium solution
                 in least squares mode,
                    PFC_SIGMA(K) <0. -> coil current K is fixed to the experimental value
                                 =0. -> coil current K is unconstrained (default)
                                 >0. -> coil current K is constrained as part of the least
                                        squares solution to be within const*PFC_SIGMA(K) of 
                                        the experimental value.  The const is affected by 
                                        the relative weighting applied to the boundary and
                                        X points relative to the coil current weights.
  
  ISO_CONFIG = character variable for selecting a tokamak configuration.  Can be used to
               load a specific tokamak when running under a different tokamak name (e.g. WRK)
                 'file: <file>' -> load isolver state file <file>  (e.g. 'file: iso_nstx-orig.nc')
               For NSTX,
                 'upgrade' -> load coil set for NSTX upgrade also the default 
                              for shots >=300000
                 'orig'    -> load original NSTX coil set or default for shots <300000
                 'pass'    -> load original NSTX coil set with passive structures (passive
                              structures not currently available)

  NISO_MODE = select the profiles to use in the solution
            = 101  -> p, <J.B> -- this doesn't seem to work well in TRANSP (see Notes)
            = 102  -> p, q  (default)

  NISO_NRHO    = number of radial surfaces to use internally in Isolver
  NISO_NTHETA  = number of poloidal rays to use internally in Isolver (default 121)

  NISO_NRZGRID = nr, nz -> number of grid points to use in the R,Z direction,
                           it is best to set these to 2**n+1  (e.g. 33 or 65 or 129).
                           Due to an output limitation, 129,129 are currently the 
                           maximum dimensions.
  NISO_MAXITER = maximum number of iterations to attempt per try on each time slice.
                 If convergence isn't achieved after this many iterations, some parameters may
                 be changed and addtional tries performed.  There can be up to 8 tries per time
                 slice.  Default NISO_MAXITER=250.
  XISO_SMOOTH  = smoothing half-width applied to input profiles prior to use
                 in Isolver, <0 for relative to 1/nzones, >0 for TRANSP xi coordinate

  XISO_PCURQ_SMOOTH = smoothing applied to internal Isolver plasma current in q mode.  
                      Additional smoothing of this metric can help improve the speed of 
                      convergence and the solution is relatively tolerant of 
                      the smoothing. (default -2 -> 2/NISO_NRHO)

  XISO_OMEGA      = relaxation factor between internal Isolver iterations.  The default
                    for <J.B> mode is 0.2, for q mode it is 0.5.
  XISO_ERROR      = Convergence error criteria. Default 1.e-6
  XISO_WARN_RATIO = when struggling, accept a relaxed error criteria by this factor (default 50.)
  XISO_LAST_RATIO = XISO_WARN_RATIO applied to the last retry, <0 to ignore (default -1)


  EQ_X_WEIGHT   = weighting for least squares matching the X point location
  EQ_REF_WEIGHT = weighting for least squares matching the prescribed boundary
  EQ_CUR_WEIGHT = weighting for least squares matching the experimental currents

  NEQ_XGUESS = the location of the nearby X points can be guessed based on the shape
               of the prescribed boundary and this info is used to constrain the solution.
                 -+1 -> guess lower/upper X point
                   2 -> guess both X points (default)
                   0 -> do not guess the X point

  EQ_CRAT   = when deriving the boundary from the psi(R,Z) solution, ensure the minimum curvature
              meets this criteria as required by TRANSP (default .08)
  EQ_BDYOFF = the boundary is offset by this amount from the separatrix in normalized psi units
              with possibly an additional offset to meet the EQ_CRAT requirement (default .01)
  NEQ_ILIM  = select the source of the limiter info as used in the free boundary solution
                -1 -> internal to Isolver state
                +1 -> external ufile
                 0 -> external ufile if provided otherwise internal (default)

  NISO_QEDGE = for p,q mode (NISO_MODE=102), select how to handle q at the edge 
               0->no modification, 1->match desired q, 2->match plasma current
               default is 2 if NLPCUR=.TRUE. otherwise default is 1

  XBDYCHK = maximum allowable difference between the prescribed boundary and the last
            closed flux surface relative to the midplane major radius.  Set less than
            or equal to zero to not check.  (default .05)

PFC ufile:
  A 2D ufile defined by PREPFC, EXTPFC can be used to input the experimental poloidal 
  field coil currents.  The ufile should have one time axis and one axis indexed 
  for each of the coil currents.  PFC_NAMES is also required.  NLPFC_CIRCUIT should
  be set appropriately.

6 General Isolver Outputs
  The following outputs are available with Isolver in least squares or circuit 
  equation mode.

   COILCURS = total poloidal current in each of the poloidal field coils -- this is just
              the number of turns * CIRCURS (multigraph of CC_<NAME>)
   CIRCURS  = circuit currents for each of the poloidal field coils (multigraph KK_<NAME>)
   PFCURS   = coil currents from PFC ufile (multigraph of PF_<NAME>)

   CC_<NAME> = total poloidal current in coil <NAME> = number of turns * KK_<NAME>
   KK_<NAME> = circuit current in coil <NAME>
   PF_<NAME> = poloidal current for coil <NAME> as input in PFC ufile

   CP_<NAME> = comparison of Isolver and PFC coil currents if NLPFC_CIRCUIT=.FALSE.
   KP_<NAME> = comparison of Isolver and PFC circuit currents if NLPFC_CIRCUIT=.TRUE.

   PSIRZ = psi(R,Z) data located in a flat RGRID*ZGRID array relative to magnetic axis
           if NPSIRZ_OUT=1 (default). The eqrplot utility, if available, can be used to 
           plot this data.  This data is suppressed if NLPSIRZ_OUT=.FALSE. (default .TRUE.)

   APSIRZ = psi(R,Z) data located in a flat RGRID*ZGRID array relative to the machine axis
            if NPSIRZ_OUT=2. The eqrplot utility, if available, can be used to plot this data.  
            This data is suppressed if NLPSIRZ_OUT=.FALSE. (default .TRUE.)

   NBPNT_MHD = 0 if limited, -1 if lower, +1 if upper, +2 if double diverted
   
   RBPMHD,ZBPMHD,PBPMHD   = R,Z,psi of point which bounds the plasma (limiter or X point)
   RXPMHDn,ZXPMHn,PXPMHDn = R,Z,psi of X point <n> for n=1,8 or 0 if the X point does not exist
   ABPMHD, AXPMHDn        = psi of points relative to the machine axis

   FBDY      = multigraph of FBDY_FREE,FBDY_REF
   FBDY_FREE = average offset of the resulting free boundary from the separatrix in 
               units of normalized psi.  This will ususally be EQ_BDYOFF unless the
               EQ_CRAT criteria needs to be met.
   FBDY_REF = average offset of the prescribed boundary from the separatrix in 
              units of normalized psi.

   IPCMP = compare TRANSP's total plasma current with the plasma current in the equilibrium
           solution.  This is useful for seeing when plasma current matching is abandoned
           by Isolver because it is struggleing when NLPCUR=.TRUE.
 
   XLIF_1,XLIF_3 = Li internal inductance relative to the free boundary as computed in Isolver
   XLIS_1,XLIS_3 = Li internal inductance relative to the separatrix

   PSI0_ISO = psi at the magnetic axis relative to the machine axis
   ISOITER  = total number of Isolver iterations at each time slice 
   ISORETRY = number of Isolver retries

6 More Isolver Notes
   - <J.B> mode doesn't seem to work very well.  <J.B> is sensitive to the metrics at the edge
     which are not well resolved on the R,Z grid.  Advancing the q profile in TRANSP while
     using <J.B> in Isolver can thrash the metrics.  Isolver q mode is much stabler in TRANSP.
   - Unfortunately, q mode has slow convergence in Isolver (Apr2010: improved convergence).  
     The rate of convergence can be improved by smoothing the internal current in Isolver 
     with XISO_PCURQ_SMOOTH.  The default XISO_PCURQ_SMOOTH=-2.0 has a smoothing half-width 
     of 2 internal Isolver zones.
   - Isolver tries really hard to find a solution because the run ends if convergence fails.
     With the default 250 iterations per try with up to 8 or so tries you can get some really 
     slow solutions if Isolver is struggling.  When running in q mode and if left on its own,
     the q in Isolver will match well to the input q except at the edge.  So Isolver will make
     small perurbations to the edge q profile to better match TRANSP's edge q (NLPCUR=.FALSE.) or
     the plasma current (NLPCUR=.TRUE.).  When struggling, this q perturbation is abandoned which
     can sometimes result in a solution but it can take up to a 1000 iterations to get to this
     point.

4 PLASMA_BOUNDARY
Method of specifying the location of the plasma boundary depends on
the geometry level switch LEVGEO.

for LEVGEO=0 set (in TRANSP namelist)
  RMAJOR=plasma major radius, cm.    RMINOR=plasma minor radius, cm.

for LEVGEO.LE.2 UFILES of major and minor radius vs. time may be
read (but the data will be time averaged if LEVGEO=0).  In the
TRDAT namelist set
  PREPOS,EXTPOS - UFILE name for major radius vs. time
  PRERMN,EXTRMN - UFILE name for minor radius vs. time

for LEVGEO.ge.3 a set of UFILES containing a time dependent Fourier
moments specification of the boundary location is required.  See
section on the TRDAT namelist - UFILES names, moments UFILES.
4 NCLASS_neoclassical
TRANSP now incorporates an interface to the famous NCLASS model[1].

The interface is still undergoing development; this write up gives
a description of the status as of 18 Sept 1998 (dmc) with some minor
updates May 2004 (rga).

Synopsis:
NCLASS can now be used in place of the traditional codes derived
from aspect ratio approximations to compute:

  improved estimate of plasma resistivity
  improved estimate of bootstrap current
  improved analysis of rotation data
  improved estimate of radial electrostatic field.

These capabilities replicate inside the time dependent model
the calculations already implemented in the widely used
"tr_neo" post-processor code (tr_neo is now included in
the TRANSP source code distribution).

The code uses a full multi-species representation of plasma 
profiles (rather than a Zeff-based parametrization), and is
valid for arbitrary geometry and collisionality regimes.  It
has been noticed e.g. that the geometry improvements are
important for chubby aspect ratio ST devices such as NSTX.

The code maintains separate velocity profiles for each plasma
specie.  Given a measurement of toroidal rotation velocity 
for a single ion specie, the code can compute the radial
electrostatic potential and then the velocity profiles for
all ion species.  The neoclassical corrections to the
relationship between plasma rotation and radial electric
field are automatically incorporated.

Related HELP file sections:

TRANSPHELP OPERATIONS NAMELIST ROTATION
  (includes section on radial electrostatic field).
TRANSPHELP OPERATIONS NAMELIST MAGNETICS

Reference:

[1] W.A. Houlberg et al., "Bootstrap Current and Neoclassical
Transport in Tokamaks of Arbitrary Collisionality and Aspect
Ratio", Phys. Plasmas 4 (9), Sept. 1997, pp 3230-3242.
5 Namelist_Control_Summary
NCMODEL = selects the nclass code used for the analysis
        = 1 -> original common block based code (1997)
        = 2 -> Houlberg's nclass fortran 90 module (2004)
The default is NCMODEL=2-- the current version.

New Ufile inputs:
VTR -- toroidal rotation of an ion species, NGVTOR specificies
  which specie;
VPR -- poloidal rotation; NGVPOL specifies which specie;
VPO -- radial electrostatic potential input (NLIVPO=.TRUE.
  to impose this data on fast ion slowing down calculation).

(Can also use NLOMGVTR=.TRUE. to specify that traditional
rotation data inputs OMG or VP2 refer to the diagnostic species
rotation as opposed to bulk plasma rotation).

Use of NCLASS results in TRANSP:
NLBOOTW -- use NCLASS bootstrap current (also set NLBOOT=.TRUE.)
  (smoothed for r/a < XL1NCJBS; default XL1NCJBS=0.1).
NLETAW -- use NCLASS resistivity
  (modified for r/a < XL1NCETA; default XL1NCETA=0.0).
NLVWNC -- use NCLASS to analyze rotation data and compute
  radial electrostatic potential profile.
  (full analysis in range XL1NCVPH < r/a < XL2NCVPH; 
   simple extrapolation outside this region; defaults:
   XL1NCVPH=0.10, XL2NCVPH=0.85).
  In predictive runs, the predicted angular velocity is used
  "as is" and NCLASS only computes the adjusted radial 
  electrostatic potential.

NCLASS model input options:

NLSQUEEZ = .TRUE. for "squeezing factor" correction.
  (See eqn B2 in Houlberg's paper.  The factor formula
  can be written as Sai=1-(Zi/Ai)*sqz.  The code employs
  an iteration where it updates the estimate of sqz,
  which depends on the neoclassical Er from the previous
  step, and recalculates until the change in sqz on
  successive iterations is small everywhere.  However, 
  there are input parameter sets for which sqz, un-
  constrained, would grow without bound.  Therefore,
  the rule -0.25 < sqz < 0.25 is imposed.)

NLTINC = .FALSE. to use Tx & Tmj, i.e. impurity temperature
  and majority temperature (as estimated by the slvtx
  subroutine); NLTINC = .TRUE. to use aggregate average Ti for 
  all species in the NCLASS calculation.  NLTINC=.TRUE. is the
  default.
  (Note: this only controls what temperatures to use as input
  to NCLASS calculations; it does not control the interpretation 
  of measured Ti input data.  For the latter, look for the 
  descriptions of the NLTIPRO, NLTI2, and NLTI2TX switches).

NCMULTI = for NCMODEL=2 only, selects how to handle multiple
    impurities during the nclass analysis.  High atomic number
    impurities with many charge states can slow nclass down 
    which is especially important when nclass is used in the 
    magnetic diffusion loop to find the neoclassical resistivity.
      -1 -> always use a single tokamakium equivalent impurity
       0 -> use a tokamakium equivalent except for 
            snapshots during the run which will use all the 
            impurities (default)
       1 -> use a tokamakium equivalent unless the radial electric
            field is being computed within nclass or for snapshots
       2 -> always use multiple impurities when they are present

TSNAP_NCLASS(10) = this can be set to an array of times during
    the run at which nclass will be called with NCMODEL=2 and the
    full radial electric field loop.  The input and output state
    of nclass is saved to <runid>_ncbox_<time>.cdf files which contain
    detailed nclass data and can be used for rerunning nclass
    with different options.  The snapshot times are triggered
    at transp output intervals.  An NCMODEL=2 error will also
    trigger an nclass snapshot.

Smoothing:
NCLASS can be sensitive to noise in pressure and temperature
gradients.  To ameliorate this the following options are
offered:

NLNCSMOO = .TRUE. to activate smoothing of temperature and
  density input profiles
TAUSMNNC = smoothing convolution time (tau) for densities
TAUSMTNC = smoothing convolution time (tau) for temperatures
  contributions from past times to the current effective
  profile shape fall off as exp(-delta(t)/tau).
XSMN_NC = radial smoothing half width for densities (r/a units).
XSMT_NC = radial smoothing half width for temperatures.

NLSAW_NC = .TRUE. to reinitialize time convolutions at each
  sawtooth event.  Time convolutions are always (re)initialized
  at run start time and at pellet events.

XSMNB_NC = radial smoothing half width for Monte Carlo fast
  ion code NCLASS output profiels (r/a units).  The applied
  smoothing for these profiles is max(XSMNB_NC,abs(DXBSMOO))
  where DXBSMOO is the general MC code output profile smoothing
  parameter, as documented.    
  (By default this is zero and the generic beam smoothing control
  DXBSMOO is used for NUBEAM -> NCLASS outputs also; default changed
  to zero by DMC 12/2008).


After smoothing, densities and temperatures are renormalized
to yield the correct total particle count and thermal energy
content.  This reduces the "lag" effect introduced by using
past time convolution smoothing, while retaining a time
averaging effect on the profile shape.
5 RPLOT_Outputs

ETAS multigraph now shows Spitzer, NCLASS neoclassical, and
aspect ratio neoclassical versions of resistivity, as well
as the resistivity actually used in the current run.

PCURNC multigraph shows NCLASS and traditional aspect ratio
version of bootstrap current, as well as the bootstrap
current actually used, as modified by smoothing options.

PTEMP_NC, PTI_NC, PTX_NC and PTMJ_NC multigraphs show ion 
temperature profiles:  original and as smoothed for input to 
NCLASS.

PDENS_NC, PNT_NC, PND_NC, PNH_NC, PN3_NC, PN4_NC, PNL_NC,
and PNX_NC multigraphs show density profiles:  original and
as smoothed for input to NCLASS.  Not all multigraphs will
be present in general -- only those multigraphs corresponding
to ion species actually present in the run.

EPOT shows electrostatic potential profiles:  input VPO
data (if any), neoclassical analysis result, traditional
"zero'th order" formulation, and the electrostatic
potential actually used for fast ion orbit calculations.

VTORMP shows toroidal rotation velocity profiles from input
data and as inferred by NCLASS for the various plasma species,
and the averaged profile used for TRANSP beam deposition and 
momentum balance calculations.  This data is on a major
radius grid; the angular velocities multigraph OMEGS shows 
the related data on a flux zone grid.

VPOLMP shows poloidal rotation velocity profiles from NCLASS.

NCFKI multigraph shows chi(i) from NCLASS as well as from
traditional aspect ratio neoclassical chi(i) fit routines;
chi(i) is based on conductive radial heat flow summed over
ion species (convective heat flow is excluded).

GFL_NC multigraph shows the neoclassical radial particle
flows, by plasma species.

QFL_NC multigraph shows the neoclassical radial heat flows,
by plasma species.

AMOM, AMOM_IMP multigraphs shows the angular momentum density as
computed by NCLASS.  The impurity species angular momentum is
only available when NCMULTI=2.



5 Beam_Data_for_NCLASS

(This is work in progress-- terms will be used by a future
version of NCLASS to compute slowing down beam friction effects).

(modified by MG Nov. 2008)

Beam-by-beam profile outputs (no longer just for NCLASS) will be present 
for any neutral beam simulation regardless of the setting of the 
namelist switch NLNB_WNC.

This is available
only for Monte Carlo fast ion species (beams and fusion
products; RF resonant species handled by the Fokker-Planck
code do not have this option at present).

If NLNB_WNC is .FALSE., species-by-species information is
still produced.  This should provide NCLASS with the 
necessary information to evaluate contributions due to
fusion products, and may be sufficient to cover the beams
as well, for experiments in which only one neutral beam per
specie was used.

beam-by-beam outputs 

  the following are profiles: functions of x=sqrt(phi/philim):

  labeling:
  nn=01 for the first beam, 02 for the 2nd beam, etc.
  (example: NB01_E1 -- density of slowing down ions due to full
  energy component of neutral beam #01, as specified in the TRANSP
  namelist).

    NBnn multigraph:
  NBnn_E1  -- density (cm**-3) full energy fraction
  NBnn_E2  -- density (cm**-3) half energy fraction
  NBnn_E3  -- density (cm**-3) 1/3 energy fraction
  NBnn_TOT -- total beam #nn density (cm**-3)  

    BDENSNB miltigraph:
  BDENSNB  --  total beam density (cm**-3) for all beam lines

  A single profile of total density (summed over fast ion species) and average perp and pll energy
  through mid-plane:

  BDENSMP -- Fast ion density at GC against major radius through the mid-plane, #/cm3 
  EBAPLMP -- Fast ion <Epll> at GC against major radius through the mid-plane, eV 
  EBAPPMP -- Fast ion <Eperp> at GC against major radius through the mid-plane, eV 
  VBTORMP -- Fast ion <Vtor> at GC against major radius through the mid-plane, cd/sec

  At the edge, an assumption of zero density beyond the plasma boundary has been made. 
  These data are summed over all fast ion species including fusion products.

     BDEPS beam deposition profile at point of deposition, total source miltigraph: 
   BDEP_T -- T, #/CM3/SEC
   BDEP_D -- D, #/CM3/SEC
   BDEP_H -- H, #/CM3/SEC
   BDEP_3 -- He3, #/CM3/SEC
   BDEP_4 -- He4, #/CM3/SEC
   BDEP_N -- Ne, #/CM3/SEC
   BDEP_A -- Ar, #/CM3/SEC
   BDEP_K -- Kr, #/CM3/SEC
   BDEP_X -- Xe, #/CM3/SEC
   BDEP_Z -- hi Z, #/CM3/SEC
	vs. deposition profile averaged over 1st orbit
   SDEP_T -- T, #/CM3/SEC
   SDEP_D -- D, #/CM3/SEC
   SDEP_H -- H, #/CM3/SEC
   SDEP_3 -- He3, #/CM3/SEC
   SDEP_4 -- He4, #/CM3/SEC
   SDEP_N -- Ne, #/CM3/SEC
   SDEP_A -- Ar, #/CM3/SEC
   SDEP_K -- Kr, #/CM3/SEC
   SDEP_X -- Xe, #/CM3/SEC
   SDEP_Z -- hi Z, #/CM3/SEC


    SDEPOAUC -- scalar, orbit averaged unconfined:
  SDEPUC_T -- 'Beam T orbit averaged, unconfined, #/SEC 
  SDEPUC_D -- 'Beam D orbit averaged, unconfined, #/SEC 
  SDEPUC_H -- 'Beam H orbit averaged, unconfined, #/SEC 
  SDEPUC_3 -- 'Beam He3 orbit averaged, unconfined, #/SEC 
  SDEPUC_4 -- 'Beam He4 orbit averaged, unconfined, #/SEC 
  SDEPUC_N -- 'Beam Ne orbit averaged, unconfined, #/SEC 
  SDEPUC_A -- 'Beam Ar orbit averaged, unconfined, #/SEC 
  SDEPUC_K -- 'Beam Kr orbit averaged, unconfined, #/SEC 
  SDEPUC_X -- 'Beam Xe orbit averaged, unconfined, #/SEC 
  SDEPUC_Z -- 'Beam hi Z orbit averaged, unconfined, #/SEC 
  SDEPUC_F4 -- 'Fusion He4 orbit averaged, unconfined, #/SEC 
  SDEPUC_F3 -- 'Fusion He3 orbit averaged, unconfined, #/SEC 
  SDEPUC_FT -- 'Fusion T orbit averaged, unconfined, #/SEC     
  SDEPUC_P -- 'Fusion P orbit averaged, unconfined, #/SEC     

    
    BDEPnn miltigraph:
  BDEPnn_E1  -- beam deposition profile (N/cm**3) full energy fraction
  BDEPnn_E2  -- beam deposition profile (N/cm**3) half energy fraction
  BDEPnn_E3  -- beam deposition profile (N/cm**3) 1/3 energy fraction
  BDEPnn_TOT -- total beam deposition profile (N/cm**3)

    BDEPNB miltigraph:
  BDEPNB     -- total beam deposition profile (N/cm**3) for all beam lines

    PBnn multigraph:
  PBEnn_E1  -- electron heating (W/cm**-3) full energy fraction
  PBEnn_E2  -- electron heating (W/cm**-3) half energy fraction
  PBEnn_E3  -- electron heating (W/cm**-3) 1/3 energy fraction
  PBEnn_TOT -- total electron heating (W/cm**-3)

    PBENB multigraph:
  PBENB     -- total electron heating (W/cm**-3) for all beam lines
	
    PBnn multigraph (also):
  PBInn_E1  -- ion heating (W/cm**-3) full energy fraction
  PBInn_E2  -- ion heating (W/cm**-3) half energy fraction
  PBInn_E3  -- ion heating (W/cm**-3) 1/3 energy fraction
  PBInn_TOT -- total ion heating (W/cm**-3)

    PBINB multigraph:
  PBINB     -- total ion heating (W/cm**-3) for all beam lines

    PBLnn multigraph (also):
  PBEnn_TOT -- total electron heating (W/cm**-3)
  PBInn_TOT -- total ion heating (W/cm**-3)
  PBTHnn    -- beam thermalization power (W/cm**-3)
  PBTOTnn   -- total beam power (W/cm**-3), PBTOT = PBE + PBI + PBTH

    PBTOTNB multigraph:
  PBTOTNB   -- total beam power (W/cm**-3) for all beam lines	

    PBTHNB multigraph:
  PBTHNB    -- beam thermalization power (W/cm**-3) for all beam lines



  The following are averages over respective slowing down distributions
  in the rotating plasma frame of reference -- i.e. velocities are 
  relative to a single toroidal rotation velocity R*OMEGA(x) attributed 
  to the thermal plasma by TRANSP and the Monte Carlo fast ion model.
  The thermal plasma angular velocity OMEGA (radians/sec) is available 
  as a profile in TRANSP simulations which include toroidal rotation.

  (Although NCLASS calculates different rotation velocities for each
  thermal ion specie, most of TRANSP still assumes that a single 
  rotation velocity is adequate to characterize all thermal ion
  species).

    VPBnn multigraph:
  VPBnn_E1 -- <v.B> (T*cm/sec) full energy fraction
  VPBnn_E2 -- <v.B> (T*cm/sec) half energy fraction
  VPBnn_E3 -- <v.B> (T*cm/sec) 1/3 energy fraction

    VPBnn multigraph (also):
  FPBnn_E1 -- <(v/vcrit)v.B> (T*cm/sec) full energy fraction
  FPBnn_E2 -- <(v/vcrit)v.B> (T*cm/sec) half energy fraction
  FPBnn_E3 -- <(v/vcrit)v.B> (T*cm/sec) 1/3 energy fraction

!MG there are no such plots
    EDPnn multigraph:
  EDPnn_E1 -- <Edep> (deposition energy, eV) full energy fraction
  EDPnn_E2 -- <Edep> (deposition energy, eV) half energy fraction
  EDPnn_E3 -- <Edep> (deposition energy, eV) 1/3 energy fraction

  The following are not strictly needed by NCLASS, but do allow
  an assessment of present deviations from the plasma-frame mono-
  energetic source expected by NCLASS.  Deviations can be caused
  by (a) fluctuations over time of the lab frame beam injection
  energy, (b) variations over time of plasma rotation velocity,
  (c) radial variations of plasma rotation velocity combined
  with radial transport (orbit scattering, anomalous diffusion,
  charge exchange neutralization & recapture) of fast ions.

    EDPnn multigraph (also):
  DEDPnn_E1 -- <RMS variance(Edep)> (eV) full energy fraction
  DEDPnn_E2 -- <RMS variance(Edep)> (eV) half energy fraction
  DEDPnn_E3 -- <RMS variance(Edep)> (eV) 1/3 energy fraction
!MG end no such plots


  The following SCALAR functions show the variance due to the
  lab frame beam injection energy fluctuations alone-- not strictly
  needed by NCLASS.

    EINJnn multigraph:
  EINJnn_E1 -- <Einj> (lab frame inj. energy, eV) full energy fraction
  EINJnn_E2 -- <Einj> (lab frame inj. energy, eV) half energy fraction
  EINJnn_E3 -- <Einj> (lab frame inj. energy, eV) 1/3 energy fraction

    EINJnn multigraph (also):
  DINJnn_E1 -- <RMS variance(Einj)> (eV) full energy fraction
  DINJnn_E2 -- <RMS variance(Einj)> (eV) half energy fraction
  DINJnn_E3 -- <RMS variance(Einj)> (eV) 1/3 energy fraction

  Injected powers for each beam line are given by graph

  PINJnn  -- (WATTS),  Beam#00 injected power.

    PINJB scalar:
  PINJB   -- (WATTS), beam injected power for all beam lines


The following summarizes momentum balance by each beam line outputs from TRANSP.

The BTQnn multigraph shows the source torques from NBI: collisions, 
JxB, thermalization; the sum is TQT.

    TQBnn multigraph :
  TQCOLnn  -- (Nt-M/CM**3), beam#nn collisional torque
  TQJBnn   -- (Nt-M/CM**3), beam#nn JxB torque
  TQTHnn   -- (Nt-M/CM**3), beam#nn thermalization torque
  TQTOTnn  -- (Nt-M/CM**3), beam#nn total torque, TQT = TQCL + TQJB + TQTH


    TQCOLNB multigraph :
  TQCOLNB  -- (Nt-M/CM**3), beam collisional torque for all beam lines

    TQJBNB multigraph :
  TQJBNB   -- (Nt-M/CM**3), beam JxB torque for all beam lines

    TQTHNB multigraph :
  TQTHNB   -- (Nt-M/CM**3), beam#nn thermalization torque for all beam lines

    TQTOTNB multigraph :
  TQTOTNB  -- (Nt-M/CM**3), beam#nn total torque for all beam lines

-----------------------------
species-by-species information (available for all runs regardless of
the setting of the namelist switch NLNB_WNC, but, only for species
actually present in the TRANSP simulation; i.e. no He3 beams in the
run => no He3 profiles in the output database-- as is the usual
practice with TRANSP output).

  possible beam species & associated label suffixes:
    _x  =>  _H (Hydrogen), _D (Deuterium), _T (Tritium),
            _He3, _He4

    Helium beams have 100% full energy fraction and no half or 1/3
    energy fractions, and so are handled differently than Hydrogen
    beams.

    Hydrogen beams multigraphs:
                  NB_F_x (fast ion densities -- by energy fraction)
                  PB_F_x (heating profiles -- by energy fraction)
                  VPB_F_x (v.B and (v/vcrit)v.B  -- by energy fraction)
                  EDP_F_x (plasma frame Edep -- by energy fraction)

    H beam profiles:
  NB_F1_x -- density (cm**-3) full energy fraction
  NB_F2_x -- density (cm**-3) half energy fraction
  NB_F3_x -- density (cm**-3) 1/3 energy fraction

  PBE_F1_x -- electron heating (W/cm**-3) full energy fraction
  PBE_F2_x -- electron heating (W/cm**-3) half energy fraction
  PBE_F3_x -- electron heating (W/cm**-3) 1/3 energy fraction

  PBI_F1_x -- ion heating (W/cm**-3) full energy fraction
  PBI_F2_x -- ion heating (W/cm**-3) half energy fraction
  PBI_F3_x -- ion heating (W/cm**-3) 1/3 energy fraction

    (all the following in the rotating plasma frame of reference):

  VPB_F1_x -- <v.B> (T*cm/sec) full energy fraction
  VPB_F2_x -- <v.B> (T*cm/sec) half energy fraction
  VPB_F3_x -- <v.B> (T*cm/sec) 1/3 energy fraction

  FPB_F1_x -- <(v/vcrit)v.B> (T*cm/sec) full energy fraction
  FPB_F2_x -- <(v/vcrit)v.B> (T*cm/sec) half energy fraction
  FPB_F3_x -- <(v/vcrit)v.B> (T*cm/sec) 1/3 energy fraction

  EDP_F1_x -- <Edep> (deposition energy, eV) full energy fraction
  EDP_F2_x -- <Edep> (deposition energy, eV) half energy fraction
  EDP_F3_x -- <Edep> (deposition energy, eV) 1/3 energy fraction

  DEDP_F1_x -- <RMS variance(Edep)> (eV) full energy fraction
  DEDP_F2_x -- <RMS variance(Edep)> (eV) half energy fraction
  DEDP_F3_x -- <RMS variance(Edep)> (eV) 1/3 energy fraction

  ---------------------------
  Helium beams multigraphs, and member profiles:
                  NBNC_HE (densities):  NBNC_He3, NBNC_He4
                  PBNC_HE (heating profiles):  PBENC_He3,PBINC_He3
                                               PBENC_He4,PBINC_He4
                  VPB_HE (v.B and (v/vcrit)v.B profiles):
                                               VPB_He3,FPB_He3
                                               VPB_He4,FPB_He4
                  EDP_HE (plasma frame depositions energies):
                                               EDP_He3,DEDP_He3
                                               EDP_He4,DEDP_He4

    (profile units and definitions parallel those with similar
    names for H beams).

  ---------------------------
  fusion product species:

    for constituent profiles, if present in simulation:

    _y =>  _4 (He4, alphas)  _3 (He3, DD fusion product)
           _T (tritons, DD fusion product)

    multigraphs:  NFNC_FUSN (densities): all NFNC_y profiles.
                  PFNC_FUSN (heating profiles): 
                                         PFENC_y & PFINC_y profiles.
                  VPB_FUSN (v.B and (v/vcrit)v.B profiles):
                                         VPB_FP_y & FPB_FP_y profiles.
                  EDP_FUSN (plasma frame depositions energies):
                                         EDP_FP_y & DEDP_FP_y profiles.

    (profile units and definitions parallel those with similar
    names for beams).


5 Model_Limitations

(a) coupling of beam forces into NCLASS has not yet been
implemented.

(b) little use is made of NCLASS computed radial flows.

(c) the neoclassical velocities / electrostatic analysis
might have problems at the plasma bdy and magnetic axis;
there is no workaround option at this time.

(updated dmc -- 6 Aug 2003)

4 MAGNETICS 
This section concerns solution or analysis of the poloidal field
diffusion equation in TRANSP.  Quantities involved:  poloidal
magnetic field, q profile or iota(bar) profile, plasma current
density profile:  all are related.

There are four main options:

  (1)  NLMDIF=.TRUE.  set an initial condition (EFIELD), specify
       a resistivity model and boundary conditions, and advance 
       the poloidal field diffusion equation predictively.
  (2)  NLQMHD=.TRUE.  set the q profile from output of the
       MHD equilibrium analysis.  ** not yet available **
  (3)  NLMBPB=.TRUE.  evolve the q profile using input data:
       Bp/Bt vs (R,t) or a vs (R,t) where tan(a)=Bp/Bt.  
  (4)  NLQDATA=.TRUE.  set the q profile from the QPR Ufile.

In all options other than (1), the solution of the poloidal 
field equation yields the resistivity profile, but non-physical 
negative values of resistivity can come out (it depends on the
quality of the q profile data, dq/dt, etc).  See Q_ANALYSIS.

The ancient option to use EFIELD during a run is no longer
supported.  EFIELD can only be used to provide an initial
condition for option (1) (this is the usual practice).

It is now possible to switch back and forth amongst the
options (1) -- (4) in the course of a run.  See Time_Switching.

5 Shared_Controls

Resistivity:

RESIS_FACTOR: scale factor applied to the resistivity profile (added Apr2007)

NLSPIZ:  set .TRUE. for Spitzer resistivity, .FALSE. for any kind of
  TRANSP neoclassical resistivity; the default model for neoclassical
  resistivity is built from an aspect ratio approximation:
  S. P. Hirshman, R. J. Hawryluk, B. Birge, Nucl. Fusion 17, 611 (1977).

  *** caution *** NLSPIZ=.TRUE. is the default, for historical reasons.
  Most modern TRANSP runs have NLSPIZ = .FALSE. explicitly set in the
  namelist.

  NLSPIZ = .TRUE. with NLRES_SAU = .TRUE. gives a slightly different
  formulation of Spitzer resistivity.

NLRESTSC:  set .TRUE. for neoclassical resistivity as implemented
    in the TSC transport code, Nucl. Fusion 33, page 372 (1993).
    NLSPIZ=.FALSE. should also be set.

NLETAW:  set .TRUE. for full generalized geometry neoclassical
  resistivity based on the NCLASS code.  NLSPIZ=.FALSE. must
  also be set.  Notes:
    (a) for technical reasons NLVSUR=.TRUE. is incompatible with
        NLETAW=.TRUE.,
    (b) the on axis values of the NLETAW=.TRUE. resistivity
        profile can be modified by setting

          XL1NCETA = (r/a value inside of which resistivity
                      transitions smoothly back towards the Spitzer
                      limit as r/a -> zero)

        This option is provided because the NLETAW=.TRUE. results
        for resistivity do not recover the Spitzer value on axis,
        and there are reasons for doubting the physicality of the
        neoclassical model there.  XL1NCETA=0.0 (no correction)
        is the default; XL1NCETA=0.1 might be reasonable alternate
        setting.

  NLETAW will be disabled if NLSPIZ.or.NLRESTSC.or.NLRES_SAU are set.

  NCLASS reference: http://w3.pppl.gov/NTCC/NCLASS/readme_nclass_pt.html

NLRES_SAU: set .TRUE. for full generalized geometry and arbitrary 
  collisionality  neoclassical resistivity as published by O. Sauter, 
  C. Angioni and Y. R. Lin-Liu in the reference given below. This set 
  of equations use a Zeff-based parametrization and are thus simpler,
  while retaining the same range of validity, than the multispecies 
  code NCLASS. NLSPIZ=.FALSE. must also be set. See also NLBOOT_SAU.
  (feature added to TRANSP by JET Collaboration -- D. Kelliher et al).

  NLRES_SAU and NLRESTSC should not *both* be set in the same run.

  set SAUTER_NC_ADJUST(1) to a value other than 1, to scale the
  electron collisionality computed in the Sauter resistivity model.
    For this controls the default value is 1.0 and the allowed range
    is 0.0 to 10.0.

Sauter reference: O.Sauter and C.Angioni, Phys of Plas 6(7), 2834 (1999)

  summary of resistivity models and allowed switch combinations:

     model      switches:  NLSPIZ    NLETAW     NLRESTSC  NLRES_SAU
     ---------------------------------------------------------------
     Spitzer (default)       T         F          F           F
     Spitzer (Sauter vsn)    T         F          F           T
     TRANSP neoclassical     F         F          F           F
     NCLASS neoclassical     F         T          F           F
     TSC neoclassical        F         F          T           F
     Sauter neoclassical     F         F          F           T

More Resistivity options:

  NLRSQ1 -- set .TRUE. to flatten resistivity profile in central
            region where q <= 1. (default .FALSE.).  The code 
            finds the resistivity at the q=1 surface and applies
            this value at all points from there in to the axis.

  NLSAWS & QSAW & XSAW_ETA -- set NLSAWS .TRUE. and QSAW to flatten 
            the resistivity profile in the central region where
            q <= QSAW.  Inside the q=QSAW surface, set the resistivity
            eta(x) = (1-XSAW_ETA)*eta(x|q=QSAW) + XSAW_ETA*eta(x)[orig.]
            If QSAW=1.0 and XSAW_ETA=0.0, NLSAWS=.TRUE. means the
            same thing as NLRSQ1=.TRUE.  (Defaults are: QSAW=1.0,
            XSAW_ETA=0.0, and NLSAWS=.FALSE.).

  NLRESIS_FLATTEN & XRESIS_FLATTEN -- set NLRESIS_FLATTEN=.TRUE. to
            unconditionally flatten the resistivity from the magnetic
            axis to x=XRESIS_FLATTEN, using the original profile value
            interpolated linearly at XRESIS_FLATTEN. XRESIS_FLATTEN
            is constrained to be between 0 (the axial value) and 1
            (the edge value).  If XRESIS_FLATTEN=0 there is no effect.
            (Defaults are: NLRESIS_FLATTEN=.FALSE., XRESIS_FLATTEN=0.075).

  These options apply to all variations of resistivity when the
  poloidal field diffusion equation is turned on.

Bootstrap Current:

NLBOOT:  set .TRUE. to include BOOTSTRAP CURRENTS in the poloidal
  field equation.  By default, a neoclassical boostrap current model 
  based on an aspect ratio approximation is employed (the source code
  is in source/magcor/bstrap.for).  An anomaly factor
        XBSTRAP          (default value is XBSTRAP=1.0)
  may be specified in the namelist.

if NLBOOT is set TRUE, the following options are also available:

NLBOOTW:  set .TRUE. to use the boostrap current computed in the
  fully general geometry NCLASS neoclassical code.  This is 
  expected to be an improvement over NLBOOTW.  If NLBOOTW=.TRUE.
  is used:
    (a) XBSTRAP can be used as with NLBOOT.
    (b) use XL1NCJBS to specify an r/a value inside of which
        the NCLASS bootstrap current is not to be believed,
        but replaced by a smooth extrapolation to zero on 
        axis.  The default, XL1NCJBS=0.1, is the minimum
        recommended value.

NLBOOT_SAU: set .TRUE. for full generalized geometry and arbitrary 
  collisionality bootstrap current as published by O. Sauter, 
  C. Angioni and Y. R. Lin-Liu in the reference given below. NLBOOT=.T.
  and NLBOOTW=.F. must also be set.  See also NLRES_SAU. If NLBOOT_SAU
  is used:  
    (a) XBSTRAP can be used as with NLBOOT.
    (b) use XL1NCJBS to specify an r/a value inside of which
        the Sauter bootstrap current is not to be believed,
        but replaced by a smooth extrapolation to zero on 
        axis.  However, it may be unnessary to carry out this 
          smoothing, in which case XL1NCJBS=0.0 may be advisable 
          (testing still in progress). 
  (feature added to TRANSP by JET Collaboration -- D. Kelliher et al).

  Sauter boostrap model options:
    Set SAUTER_NC_ADJUST(2) to a value other than 1 to scale the
        electron collisionality used in the Sauter bootstrap model;
    Set SAUTER_NC_ADJUST(3) to a value other than 1 to scale the
        ion collisionality used in the Sauter bootstrap model.
    For these controls the default value is 1.0 and the allowed range
    is 0.0 to 10.0.

Sauter reference: O.Sauter and C.Angioni, Phys of Plas 6(7), 2834 (1999)

  summary of bootstrap current  models and allowed switch combinations:

     model      switches:            NLBOOT    NLBOOTW    NLBOOT_SAU
     ---------------------------------------------------------------
     (default: NONE)                   F         T/F        T/F
     TRANSP aspect ratio approx.       T          F          F       
     NCLASS neoclassical               T          T          F       
     Sauter neoclassical               T          F          T

Driven Currents:

NMCURB =1, 2, or 3 to include BEAM DRIVEN CURRENTS in the poloidal field 
  equation.  NMCURB=1 is the default.  For more information see namelist
  controls for the beam model.  The current is calculated with
  neoclassical shielding (nubeam/jbshld.for).  To use the simplified
  Spitzer shielding factor, (1-Zb/Zeff), set NMCURB=2.  To suppress
  the beam driven current altogether, set NMCURB=0.

  NMCURB=1 is neoclassical: Hirshman Phys. Fluids vol. 21 No. 8 Aug 1978
  NMCURB=2 is Spitzer, (1-Zb/Zeff), (no trapping correction)
  NMCURB=3 is updated neoclassical:  Y.R. Lin-Liu, 
                F.L. Hinton, Phys. Plasmas 4 (1997) 4179
  NMCURB=0, no fast ion driven current.

NLLH:  set .TRUE. for Lower Hybrid driven currents; see description
  of Lower Hybrid current drive model.

See also the section on smoothing (of drivent current profiles).

5 NLMDIF
NLMDIF=.TRUE. ==>

TRANSP solves the 1d poloidal field diffusion equation to advance the
plasma current profile in time.  The equation is solved in such a way
as to match the measured total toroidal plasma current precisely.  In
addition a Zeff/resistivity adjustment algorithm may be used to match
surface voltage data.  An initial condition must be set:  see EFIELD.

Poloidal Field Solver CONTROLS:
===============================
NLPCUR:  set .TRUE. to match the plasma current.  This is the
  default.  Set NLPCUR = .FALSE. for PREDICTION of the evolution
  of total plasma current (not matching the data exactly, except
  during initialization right at the beginning of the run).
NLVSUR:  set .TRUE. to match surface voltage data.  If NLPCUR=.T
  then this is done by adjusting Zeff for resistivity as a function
  of time.  If NLPCUR=.F then NLVSUR=.T is required, the surface
  voltage data is used as a boundary condition for advancing the
  field, and plasma composition Zeff is used in evaluation of the
  plasma resistivity.  Set NLVSUR = .FALSE. to predict a surface
  voltage that may not match the measured data precisely.

6 NLQLIM0
Protection against axial current density j->0, q->infinity on axis:
-------------------------------------------------------------------
  If q profile input data with large axial values are provided, or
  if the poloidal field diffusion equation is used predictively
  in a case with large off axis current drive, or a sufficiently
  large bootstrap current, it is not unusual for the toroidal 
  voltage to change sign in the core of the plasma.  This will
  reverse the ohmic current, and can cause the total current on
  axis to change sign as well, leading to a q=infinity surface.

  Such field configurations are incompatible with many tokamak
  physics assumptions built into TRANSP's MHD equilibrium and
  heating models, and will cause the code to crash.  In fact, if
  q becomes too large near the axis (even before appearance of
  a pole singularity and sign-reversed interior region), several
  of the available MHD solvers are likely to fail.  And they 
  should: theory indicates that no MHD equilibrium should 
  exist.

  But, such cases have also become important experimentally: e.g.
  the JET/JT-60 Lower Hybrid driven axial "current hole" experiments
  in which field tilt measurements show creation of a q->infinity
  core region.

  It is desirable to create a way for TRANSP to survive these
  configurations to enable further study.  Here it is:

    NLQLIM0=.TRUE.
    QLIM0=<max allowed axial q value, say 8.0>.

  This will constrain the axial q from climbing to a value
  greater than max(QLIM0,2*qmin), where qmin is the minimum
  value occuring anywhere in the profile.  In predictive mode,
  a non-physical driven current localized on axis will be 
  applied to constrain the evolution of q on axis to stay 
  within the specified bound.  This non-physical current is 
  available in RPLOT as CURQLIM and is part of the PCURS multigraph.

  By default, when NLQLIM0/QLIM0 are activated, the pressure profile
  (PMHD_IN) provided to the equilibrium codes will also be flattened
  in the QLIM0 region.  The fast ion models will see a large anomalous
  diffusivity in the region, consistent with theoretical results
  indicating rapid island growth and 3d MHD reconnection events in
  the region, the dynamical details of which are well beyond TRANSP's
  capabilities of course.

  The flat pressure / high diffusivity region will apply in the
  axial region where q > max(QLIM0,2*qmin) + DQ_PLIM0, where
  DQ_PLIM0, a namelist input, defaults to -0.5.

  A lower limit on the fast ion anomalous diffusivity can be set
  in this region can be set by using the namelist variable DANOM_QLIM0
  (default value is 0.0).

5 NLQMHD

Use NLQMHD=.TRUE. to have the Q profile evolution set by MHD
equilibrium analysis (least squares analysis of magnetics
data including Bp/Bt profile measurements, probes, coils, etc).

** not yet available **  dmc 6/95

5 NLMBPB
Use NLMBPB=.TRUE. to specify that the evolution of the Q profile
is to be controlled by Bp/Bt data (BPB or BPA data) -- see the
neighbouring topic on Ufiles.  In this case the poloidal field
diffusion equation is inverted to infer a resistivity profile,
as described in the Q_Analysis neighbouring topic.

Then, specify

  XUSEBPB=<last valid r/a value for Bp/Bt data>

to set the Q profile from Bp/Bt data, for r/a btw 0 and XUSEBPB,
and to extrapolate the Q profile so as to match the total 
measured plasma current, in the region r/a .gt. XUSEBPB.  Note,
the extrapolation could imply negative or otherwise unexpected
edge current density values.

5 NLQDATA
Use NLQDATA=.TRUE. to simply input a q profile evolution which
the code should track.  This Ufile is specified to TRDAT in
the usual manner:

  PREQPR
  EXTQPR

specify the Ufile filename prefix and extension.  

Caution:  the q profile input data and the total measured plasma 
current input data may not be consistent.  If you specify

  NLPCUR=.TRUE.  ! (this is the default)

then the q profile is modified in the edge region, from 
r/a = XUSEBPB out to the edge, to force consistency with the
plasma current data.  On the other hand, if you specify

  NLPCUR=.FALSE.

The entire q profile is used without modification, and the
total plasma current may not be matched.

5 Time_Switching
New in June 1995, it is possible to switch in time between
using the poloidal field diffusion predictive equation or
some other data source for specifying the evolution of the q
profile.  The following controls should be set:

  NQMODA(i) = Q profile option in time interval i (max 15 values)
  NQMODB(i) = auxilliary control switch for time interval i.
  TQMODA(i) = time to switch from interval i to i+1 (max 14 values)
     defaults:  TQMODA(i)=+infinity for all i; no time switching.
  TAUQMOD   =  continuity transition time -- when switching
     from prediction to data, a time transition time window
     must be provided so that the q profile change is not
     discontinuous.  Default value:  0.025 secs.

The time intervals must be entered in order, so that

  TQMODA(i) + TAUQMOD  <  TQMODA(i+1)

is always satisfied.

The NQMODA values have the following meaning:

  NQMODA(i)=1:  use the predictive poloidal field equation
    (NLMDIF=.T).  Then also:
       NQMODB(i)=1  ==>  NLPCUR=.T, NLVSUR=.F  (the default)
       NQMODB(i)=2  ==>  NLPCUR=.T, NLVSUR=.T
       NQMODB(i)=3  ==>  NLPCUR=.F, NLVSUR=.T
         (These switches described under the NLMDIF topic).
  NQMODA(i)=2:  use q profile from MHD analysis.
  NQMODA(i)=3:  use q profile from Bp/Bt data.
  NQMODA(i)=4:  use q profile from QPR Ufile.
       NQMODB(i)=1  ==>  NLPCUR=.T             (the default)
       NQMODB(i)=2  ==>  NLPCUR=.F
         (see the NLQDATA topic).

Cautions:
  ->  If Te is predicted, NLVSUR=.T is not allowed.
  ->  If Plasma Composition Zeff is to be inferred from the
poloidal field diffusion equation solution, this requires
NLMDIF=NLPCUR=NLVSUR=.T

These cautions imply that certain option selections may be
invalid in certain time intervals.
5 Q_Analysis
When the q profile and d/dt(q profile) are determined from
input data rather than predicted from the poloidal field
diffusion equation, the input data is then analyzed as follows...

Analysis Summary
----------------

Given the q profile, Ampere's Law can be used to get profiles
of either toroidal current density Jt or the useful flux
surface averaged dot product <J.B>.

Then, by Faraday's law, with x ~ r/a,

   d/dt(q profile) ==> d/dx(voltage profile)

and the measured surface voltage is taken as the boundary
value.  Then the current density <J.B> and electric field
<E.B> profiles are available.  Driven currents are supplied
from other physics models (beams, bootstrap, LH).  Then, 
from Ohm's Law, 

    resis*(<J.B>-<J.B>driven) = <E.B>  ==>
    resis = <E.B>/(<J.B>-<J.B>driven)

and so the results of this analysis is a resistivity profile
inferred from the input data.  Caution -- this resistivity
profile can be negative -- TRANSP considers it output only.
Further caution:  Negative Ohmic heating powers can arise,
this might indicate problems with the data (SEE ALSO the
neighbouring section Poh_options).

The resistivity analysis output is philosophically similar
to the chi(e) output from an electron power balance analysis.
Non-physical values may indicate a problem in the data.

SUGGESTION:  smooth the BPA or BPB or Q input data.  Otherwise
noise in the time derivative will strongly affect the 
Faraday's Law calculation.
5 Poh_options

To circumvent negative ohmic heating powers when using Q
analysis mode, one may set the namelist control

  NMODPOH=2  (default value is =1).

This specifies evaluation of POH using the formula

  POH = eta*J^2  (ignoring non-ohmic currents)

with the classical or neoclassical resistivity eta being
used, instead of the value (possibly negative) inferred 
from the Q data analysis.  For the resistivity calculation,
Zeff = [plasma comp. Zeff]/CZEFFM is used, along with
the current electron temperature and density.

This guarantees a "reasonable" value of POH, but the
resulting poloidal field power balance

  Poh + d(<Bp**2>)/dt = Poynting Flux

will be violated, in general!  Any violation of the
poloidal field power balance can be viewed using the
RPLOT multigraph MGBAL.  Also, the voltage profile
VPOH = eta*J(ohmic) can be seen on the VCHK multigraph
and this will deviate from the standard toroidal loop
voltage profile, if MGBAL is failing.

Note these commments apply only for the Q data analysis
mode, and do not come up when using the poloidal field
diffusion equation predictively.  If/when the predictive 
poloidal field diffusion equation is used, NMODPOH has
no effect.  See the topic Q_analysis.

Note on fast ion model:  in the RPLOT output, BPOH gives
the power coupling from the OH circuit to the fast ions,
as coupled through the toroidal electric field (or the
toroidal loop voltage).  If noisy q(x,t) data has been 
provided in Q analysis mode, the toroidal loop voltage
will fluctuate wildly, and large amounts of power can
be coupled to the fast ions via BPOH.  But, this 
fluctuation is also suppressed with NMODPOH=2 -- it is
VPOH=eta*J(ohmic) that is provided to the fast ion models.

5 EFIELD
INITIALIZATION system (EFIELD).  If NLMDIF=.T is used, EFIELD 
is used for an initial condition at t=TINIT only.  EFIELD is
only used when starting the run with NLMDIF=.T (q predicted).

----------------------------------------------------------------
 *New April 1995 -- if NEFLD=6, use Bp/Bt data to initialize
  the current profile.  Then the voltage profile is gotten from
  resistivity and might not match the input data.  Bp/Bt data
  must be provided.
 *New June 1995 -- if NEFLD=7, initialize using q profile
  Ufile data.
 *Disabled July 2002 -- NEFLD=2,4,5 options ** disabled **
  code still exists, can be restored at user request, as long as
  the user gives test data
----------------------------------------------------------------

[ For optional initialization plot output (set NLXINI=.TRUE.) ]

The following describes NEFLD options, NEFLD less than 6
========================================================

An initial condition must be defined for the poloidal
field partial differential equation.  The approach used in TRANSP is
to produce a set of voltage and iota-bar (equiv. to plasma current)
profiles consistent with Maxwell's equations, the chosen plasma
resistivity model, and selected data.  The following data supply
boundary conditions which are always satisfied both by the initial
condition options described here, and by the poloidal field solver.
  total plasma current
  time derivative of total plasma current
  time derivative of toroidal flux enclosed in plasma.  This quantity
is determined from the plasma bdy description, the external toroidal
field, and MHD equilibrium calculations.  These data combined 
determine:
  iota(bar) = (1/q) at the plasma boundary
  the slope of the voltage profile at the plasma boundary
In addition, if NLVSUR=.TRUE., there is the condition:
  the voltage toroidally around the flux surface at the plasma bdy.
  The resistivity Zeff parameter will be adjusted to match this 
  condition.  The resulting value of Zeff will depend on ELECTRON
  TEMPERATURE and the selected resistivity model.  Caution, only
  the simplified aspect ratio approximation neoclassical resistivity
  model can be used with NLVSUR=.TRUE.; NLETAW=.TRUE. is not
  compatible with NLVSUR=.TRUE.
If NLVSUR=.FALSE., the resistivity Zeff is input and the resistivity
  (Spitzer or neoclassical) is determined using the 
  ELECTRON TEMPERATURE data.

In addition there are these "definitional" constraints at the
magnetic axis (toroidal flux coord xi=0.0):
  zero poloidal field
  zero slope in voltage profile
These two conditions are always satisfied by the initialization system
and by the time dependent poloidal field solver.

EFIELD INITIALIZATION options:  The EFIELD "pseudo-equilibrium" 
solution is completed by specifying an analytic form

  V(xi)=V1 + V2*(xi**2) + alpha*(1-xi**XPEFLD)**2

for the voltage profile.  (the current profile and iota(bar) will
follow from resistivity).  In this formula,
  xi is the relative flux coordinate (flux surface label; 0=mag. 
     axis, 1=plasma bdy, behaves roughly like r/a).
  XPEFLD is an exponent, .gt. 1.25, specified as NAMELIST INPUT.
  V1+V2 is the SURFACE VOLTAGE (if NLVSUR =.TRUE. the resistivity
    will be adjusted to make this consistent with the correct total
    plasma current; if NLVSUR=.FALSE. the surface voltage itself
    will be adjusted, in context of fixed resistivity profile, to
    produce the correct total plasma current).
  V2 is determined from the slope of the voltage at the plasma bdy.

  alpha is a FREE PARAMETER whose value will be determined by namelist
input of one additional constraint on the system.  These constraints
are available:
  (a)  alpha=0.0 - use parabolic voltage profile
SPECIFY NEFLD=3, QEFLD=0.0

  (b)  match "q" at a particular radius.
SPECIFY NEFLD=3, QEFLD=q:input, RQEFLD=x value where 1/(iota(bar))
must match q:input.  If RQEFLD < 0.0 then abs(RQEFLD) is the midplane
half-width in CM of the flux surface at which the q value should be 
matched; if RQEFLD >= 0.0 then RQEFLD is the xi=sqrt(phi/philim) 
normalized flux location where the q value should be matched.  If the
requested location is beyond the plasma boundary, the code revers to 
option (a).

  (c)  Option currently disabled: match li/2+beta input data.  
SPECIFY NEFLD=4.  A fudge factor FLEFLD (default value =1.0) is 
available.  Code will make simulated li/2+beta match 
FLEFLD * (measured li/2+beta).

  (d)  Option currently disabled: find voltage profile such 
that plasma composition and resis-tivity Zeff's agree:  SPECIFY 
NEFLD=5  (also NLVSUR=.T, NLPCUR=.T required).

AUXILLIARY EFLD CONTROLS:
  The voltage correction exponent XPEFLD default to a value of 2.0
to yield a quartic correction function with zero slope at axis and
bdy and zero value at bdy (so that adding any multiple of this 
function does not affect the boundary conditions).  Set XPEFLD to
a larger number to cause more of the corrective variation to occur
out towards the plasma boundary.

  EFLD can fail if the voltage profile changes sign near the center,
since a bidirectional plasma current will result and the total plasma
current may not be reachable.  To ameliorate these problems set
  VLPMIN = minimum voltage allowed (anywhere in voltage profile)
  VLPMML = VLPMML*(surface voltage) set as minimum allowed voltage.

  If a bad constraint is set or the ELECTRON TEMPERATURE implies a
peculiar resistivy profile shape, EFLD can fail in any case.
5 Smoothing_Options
In the presence of large driven currents, the predictive solution
of the poloidal field diffusion equation can fail.  In particular
the bootstrap current while large just off axis can go to zero on
axis; if the current is overdriven and the Efield changes sign,
this can cause a negative ohmic current to develope on axis.  A
"current hole" can develop. For a number of reasons, this tends
to cause failures in TRANSP simulations.

[Note: NLQLIM0 and QLIM0 (nearby topic) can be used to provide an 
ad hoc seed current and prevent current holes, but, the simulation
can still fail in the presence of strong driven currents with lots
of radial structure].

The following ad hoc smoothing controls are sometimes useful:

NBOOSM -- smooth the innermost NBOOSM zones of the bootstrap
current.  Default NBOOSM=2.  NBOOSM=1 or less ==> no smoothing.
(Note NBOOSM affects old aspect ratio approximation results only;
for NLBOOTW=.TRUE. or NLBOOT_SAU=.TRUE., use XL1NCJBS -- see 
shared controls section).

The following all have default values of zero.  All control
radial smoothing for driven current profiles, with the number
specifying +/- the number of zones in the sliding triangular
weighted average smooth.

NJSMBOOT -- bootstrap current smoothing factor
NJSMBEAM -- fast ion driven current smoothing factor
NJSMLH   -- Lower Hybrid driven current smoothing factor
NJSMEC   -- ECRF driven current smoothing factor
NJSMIC   -- ICRF driven current smoothing factor

The controls {NJSMLH,NJSMEC,NJSMIC} for RF driven currents, if set,
will also apply an additional, total current preserving smoothing step 
at the magnetic axis.

For these RF controls a value of -1 will cause the axial smooth to be
applied but no further smoothing of the profile; default values (0)
provide for no smoothing whatsoever.  Some of the RF codes tend to
return intermittently spiked axial current drive which is treated 
by this setting.

5 Hints
[dmc 3 Feb 1993] ... notes on PPPL practice

The poloidal field diffusion equation
predictive solution can fail (usually with zero or negative
current density on axis) if bootstrap or driven currents are
large enough.  In such cases use of an alternative source for
the q profile might be preferred.  The Monte Carlo fast ion
orbiter can also fail of j on axis gets too small (q on axis
too large).

Evidence seems to indicate that beam driven and bootstrap currents
are real so usually NLBOOT=.T and NMCURB>0 are used.  However, the
bootstrap currents can cause trouble (e.g. negative current density
on axis, q=infinity surface) especially if the code is started with 
an unrealisticly high plasma pressure.

People on different tokamaks have different opinions about how
NLSPIZ should be set.  NLSPIZ=.FALSE., which yields neoclassical
resistivity, is usually preferred.

(NEFLD=4 is currently disabled) If li/2+beta data is routinely 
available, NEFLD=4 may be the most convenient NLMDIF=.T 
initialization switch setting (comment applies mainly to circular 
cross section tokamaks).

With NLMDIF=.TRUE.,

If good Zeff data is available, NLPCUR=.T and NLVSUR=.F are usually
used.  This matches the plasma current and predicts the surface
voltage which is then later compared to measurement.

If no Zeff data is available, NLPCUR=NLVSUR=.T might be tried, to
get an estimate of Zeff from resistivity considerations.  The Te 
data must be excellent for this to work.

5 Ufile_Data
(plasma bdy vs. time -- described elsewhere)
(Zeff -- may be used for resistivity -- described elsewhere)
(Electron Temperature -- critical for resistivity --
   described elsewhere)

partial list:
TRDAT:  PRECUR,EXTCUR - the plasma current UFILE vs. time (amps)
        PREVSF,EXTVSF - surface voltage vs. time.  This is defined 
  as the voltage toroidally around the surface which at each given
  time describes the boundary (last closed surface) of the plasma.
        PREL2B,EXTL2B - li/2+beta or "lamda" vs. time.  A derived
  magnetic quantity (may not be appropriate for noncircular cases).
        PREBDI,EXTBDI - diamagnetic beta vs. time
        PREDFL,EXTDFL - displaced (para- or diamagnetic) toroidal 
  flux vs. time (Webers).

        PREBPB,EXTBPB - PROFILE of tangent(field line tilt) vs.
  time and major radius - compare data with TRANSP calculation in
  RPLOT using the FBP profile multigraph.  Bp/Bt data.

        PREBPA,EXTBPA - PROFILE of field line tilt angle a vs.
  time and major radius - compare data with TRANSP calculation in
  RPLOT using the FBP profile multigraph.  tan(a) = Bp/Bt.

	PREQPR,EXTQPR - Q profile from Ufile data.

DEFAULTS (generally .FALSE.) SET IN "port.for" (See documentation 
section at top of document)

TRANSP namelist switches:

NLI2PB:  set .TRUE. to read li/2+beta(poloidal) data
NLBDIA:  set .TRUE. to read diamagnetic beta TOROIDAL data
NLBPDA:  set .TRUE. to read diamagnetic beta POLOIDAL data
  at most one of (NLBDIA,NLBPDA) may be set to .TRUE.
NLDFLX:  set .TRUE. to read diamagnetic flux data
NLEDIA:  set .TRUE. to read diamangetic energy data

5 Field_Orientation_Controls

DMC September 2006 -- these switches can be important!  See comments
below...

There are two namelist logical switches that define the orientation
of the toroidal field and toroidal current:

  NLBCCW=.TRUE.  ! orientation of B (.TRUE. for counter-clockwise)
  NLJCCW=.TRUE.  ! orientation of Ip (.TRUE. for counter-clockwise)

Here "counter-clockwise" is as seen looking down on the tokamak from
above.

Often, the settings of these switches have little effect on the
transport calculation.  Angular momentum balance, in particular, is
defined such that positive Vphi means "with the plasma current"; this
turns out to be the way to make the balance calculation relatively
insensitive to the setting of these switches.  

BUT: getting these switches right IS important for low field devices
(e.g. STs) AND sometimes even in conventional tokamaks where off axis
beam injection is employed.

For beam deposition the potential effects are:

  (a) whether the FLR step from ionization point to guiding center is
towards, or away from, the plasma magnetic axis;
  (b) how the poloidal field modifies the initial parallel velocity 
(v.B)/|B|, and hence vpll/v of deposition, trapping fraction, etc.

(Many thanks to Jim Conboy and Clive Challis at JET for showing the 
importance of these switches for some experimental simulations).

(For neutral beams centered on the magnetic axis the above effects tend 
to cancel out).

These switches can have slight effects on transport and beam heating
or momentum transfer, if the plasma geometry and/or beam configurations
are strongly updown asymmetric.  Also, the signs of some rotation profile
outputs from NCLASS may be affected.

CAUTION:  Since these switches have been thought to have a weak effect, 
it is often the case, in the average TRANSP run, that they have not been 
set correctly from the experimental configuration!

These orientations can also be set from the MHD equilibrium boundary
or full equilibrium data inputs to TRANSP as an option-- the codes that
compute these TRANSP inputs now generally have the ability to save the
field and current orientation signs.  **This should be used wherever
possible** to ensure that the settings are correct.

5 Toroidal_current_vs_JdotB
(DMC Feb 2010-- transcription of notes, "neoclassical currents").

  !  <Jtor>a = <Jtor/R>/<1/R> = (R*Btor)*<1/R**2>/(<B**2><1/R>) * <j dot B>
  !
  !     < > means differential volume average over flux surface
  !     < >a means differential area average over flux surface

To show this here is a derivation based on an idea from Mike Z that we
applied to TRANSP bootstrap current interpretation back in the TFTR era.
It uses a conservation law in the poloidal direction to infer a general
property of <J.B>/B**2 that is helpful for obtaining the toroidal current
relation.  It is valid for any axisymmetric tokamak equilibrium.

Locally, Jtor = (J.B)Btor/B**2; Jpol = (J.B)Bpol/B**2.  

For any flux coordinate x, the derivative of enclosed poloidal current 
dIpol/dx is constant around the flux surface at x, a consequence of 
continuity div(J)=0, no charge source in our quasineutral plasmas. 
Equivalently (through Ampere's Law) (R*Btor) is a flux surface 
invariant.

Anywhere on the surface at x, dIpol/dx = (2pi*R/grad(x))*Jpol = 
(2pi*R/grad(x))*(J.B)Bpol/B**2= const. on flux surface. And 
Bpol = grad(Psi)/R = dPsi/dx*grad(x)/R, with Psi(x) the enclosed 
poloidal flux.  The locally varying metric terms R and grad(x) cancel, 
so we have dIpol/dx = 2pi*dPsi/dx*(J.B)/B**2.  Key conclusion: 
(J.B)/B**2 is invariant around a flux surface.

Now, Definitions:
The differential area average 
   <f>a = [line integral](dl*f/grad(x))/[line integral](dl/grad(x))
The differential volume average 
   <f>=[line integeral]dl*f*2pi*R/grad(x)/[line integral]dl*2pi*R/grad(x)

The identity
   <f>a = <f/R>/<1/R>
follows promptly from the definitions.

I seek the relationship between <Jtor>a and <J.B>; <Jtor>a = <Jtor/R>/<1/R>.
This will be helped by being able to take (J.B)/B**2 and (R*Btor) out of the
flux surface averaging operator:

<Jtor/R> = <(J.B)Btor/B**2/R> 
         = (J.B)/B**2<Btor/R> 
         = (J.B)/B**2*(R*Btor)*<1/R**2>

It is easily shown that the flux surface invariance of (J.B)/B**2 implies
   (J.B)/B**2 = <J.B>/<B**2>

So, putting it together:

<Jtor>a  =  <Jtor/R>/<1/R>
         =  <J.B>*(R*Btor)*<1/R**2>/(<B**2><1/R>)

The metric flux surface averages <1/R> and <1/R**2> are accurately 
evaluated numerically and available (in RPLOT these are GRI and GR2I 
respectively).  The profile of <B**2> (GB2 in RPLOT) is also available.
The vacuum field (R*Btor)vac is available as a scalar function of time,
BZXR in RPLOT, and the profile GFUN gives (R*Btor)/(R*Btor)vac.

5 RPLOT_Outputs

If Bp/Bt data is present, the following scalar functions may be of
interest:

   DRBPB = R(BP=0,Bp/Bt data)-R(MHD AXIS) -- mag. axis discrepancy
   XCURBPB = Pcur/[Bp/Bt inferred plasma cur] -- comparison of 
     Bp/Bt data to total plasma current data.

Useful scalar multigraphs:

   VSCMP -- surface voltage comparison

   ZEFF0 -- MAGDIF and PC Zeff comparison

Useful profile multigraphs:

   PCURS -- toroidal current densities, may be area integrated.

   PLJBS -- <J.B> profiles

   PLJBXTS -- <J.B> driven profiles
         PLJBXTR = <J.B> - 1/resis * <E.B>, 
           resis=neoclassical or Spitzer resistivity, depending
                 on value of NLSPIZ and NLETAW switches

   ETAS -- resistivities

   QP -- q profiles comparison:  q used or predicted, q from
         surface averaged Grad-Shafranov equation, q from Bp/Bt
         data (if available).

   VCHK -- voltage check (Faraday's Law check).

   MGBAL -- poloidal field energy balance check.

   FBP -- comparison of Bp/Bt used to Bp/Bt input data.

(This list may not be complete...)
4 DATA_SYMMETRIZATION
When electron temperature, density or any other profile data is 
"two-sided", i.e. covers the entire plasma midplane from R0-A to 
R0+A, it is necessary to specify a "symmetrization algorithm" which 
will allow TRANSP to map the data to flux surfaces of radius running
from 0 to A (a generalized coordinate system is used for 
non-circular plasmas).

New March 1992-- all symmetrization options are available for 
ALL TYPES of profile inputs, not just electron temperature and 
density.

In what follows, xxx stands for NER, TER or other three letter combo
which identifies namelist controls for density, temperature, or other
profile data, respectively.

set NRIxxx=3 to indicate symmetrizable profile input data.

other values of NRIxxx:
  =1 if UFILE data covers major radii R0 to R0+A
  =2 if UFILE data covers major radii R0-A to R0
  =4 if UFILE contains Abel inverted data with minor radius as
    position coordinate, covering range 0 to A.
  =5 if UFILE contains data already mapped to the TRANSP 
    flux coordinate label sqrt(tflux/tflux@bdy)
  =6 if UFILE contains data mapped to normalized poloidal flux

If NRIxxx is not 3 then NSYxxx=0 is required.

NEW AUG 1986 -- SET NRIxxx=-n (-1, -2, ... , OR -4) to specify that
the UFILE is ALREADY defined vs. NORMALIZED spatial coordinate r/a or
(R-R0)/a.

If NRIxxx=+/-3 for electron temperature or density data, then set 
NSYxxx=1,2 or 3 or 4 is required to select symmetrization algorithm:

  NSYxxx=1:  "onion skin" or "slice and stack" symmetrization 
algorithm.  Let f(R) be the input profile.  Let h be a test value.
If l is the length of the region in the unsymmetrized data f(R) for 
which f(R) .ge. h, then define g(l/2) = h.  The profile g(r) con-
structed in this manner is the symmetrized profile.  Notes:
  the region of length l need not be connected.
  the output profile g(r) satisfies max(g(r)) = max(f(R))
  the output profile g(r) is monotonic decreasing vs. r

  NSYxxx=2:  "in/out average".  Use the TRANSP MHD geometry to
determine the locations of the two intercepts of each flux surface
with the midplane.  The simple average of the unsymmetrized data at 
these two points constitutes the symmetrized data value for the 
flux surface.  Notes:
  the output profile is not necessarily monotonic
  the peak value may be reduced
  algorithm depends on accuracy of TRANSP MHD and boundary data.

  NSYxxx=3:  "R*dR weighted in/out average".  Use the TRANSP MHD 
geometry to determine the locations of the two intercepts of each 
flux surface with the midplane. The weighted average of the profile 
at the inner and outer flux surfaces is given by
    Navg = (Nin*Rin*dRin+Nout*Rout*dRout)/(Rin*dRin+Rout*dRout)
where Rin,Rout are the major radii and dRin,dRout are the flux
surface spacings at the inner and outer intercepts.  Same
Notes applies as for NSYxxx=2.

  NSYxxx=4:  "R weighted in/out average".  Use the TRANSP MHD 
geometry to determine the locations of the two intercepts of each 
flux surface with the midplane. The weighted average of the profile 
at the inner and outer flux surfaces is given by
    Navg = (Nin*Rin+Nout*Rout)/(Rin+Rout)
where Rin,Rout are the major radii at the inner and outer flux surface
midplane intercepts.  Same Notes applies as for NSYxxx=2.  This option
is mainly provided as a compatibility feature, since old versions of
TRANSP applied this weight when symmetrizing electron density (NER)
data and other density profiles, under NSYxxx=2.
   
Note on ECE data (DMC March 1992)-- electron temperature may be 
specified in an ECE Ufile of temperature vs. time and ECE frequency
in GHz (viz. TRDAT namelist controls PREECF,EXTECF to set the ECE
Ufile prefix and suffix).  ECE data is mapped from frequency to 
major radius in TRANSP.  The same mapping and symmetrization 
controls are available as for other profile data-- i.e. use 
NRIECF to specify the coverage; if NRIECF=3 use NSYECF to
specify the symmetrization algorithm.  Note when using ECE
data, NRIECF values of +/- 4 or +/- 5 are illegal.

For compatibility with old namelists, the mapping and symmetrization
may be controlled with NRITER and NSYTER if NRIECF and NSYECF are
omitted from the namelist.

There is no longer an option to choose TRDAT or TRANSP for doing
the ECE frequency to radius map.  The map is always done in TRANSP.

When ECE data is input vs. (frequency & time), TRANSP (trdat) looks for
the ECE harmonic as a scalar "HARMONIC" in the input Ufile.  If this is
not found, the namelist variable NHECFT is used.

4 ELECTRON_DENSITY
  specifying electron density input data UFILES-- see section on 
TRDAT namelist.
  specifying data spatial range, mapping and symmetrization options:
see DATA_SYMMETRIZATION

SUMMARY OF NAMELIST CONTROLS:
TRDAT:
PRENER,EXTNER - specify profile data UFILE name
NLRNNE,PRELID,EXTLID - IF(NLRNNE) specify line integral density data
as profile renormalizer vs. time

TRANSP:
NRINER,NSYNER - profile mapping/symmetrization controls
FNEMIN - minimum allowed density

  (DMC March 1992-- the controls NLSHNE and NLSHNT have been deleted
from the namelist.  These options were for the very old concentric
circular geometry TRANSP, which is hardly used any more).
4 MINORITY_ION_DENSITY
  specifying minority ion density input data UFILES-- see section on 
TRDAT namelist.
  specifying data spatial range, mapping and symmetrization options:
see DATA_SYMMETRIZATION

SUMMARY OF NAMELIST CONTROLS:
TRDAT:
PRENMR,EXTNMR - specify profile data UFILE name
PREFMN,EXTFMN - specify 1d Ufile containing minority fraction
                nmin/ne as a function of time
One may specify one or the other of these input Ufiles but not both.

TRANSP:

FRMINI -- constant fraction nmin/ne if NO UFILE is provided to
specify the minority ion density.

NRINMR,NSYNMR - profile mapping/symmetrization controls for profile
input data
FNMMIN - minimum allowed density
4 ELECTRON_TEMPERATURE
  specifying electron temperature input data UFILES-- see section on 
TRDAT namelist.
  specifying data spatial range, mapping and symmetrization options:
see DATA_SYMMETRIZATION.
  using ECE electron temperature data-- see DATA_SYMMETRIZATION.
  Te prediction:  see ELEC_PWR_BALANCE.  NOTE:  Te measured UFILE
data must be provided even when Te is also being predicted by
TRANSP.

SUMMARY OF NAMELIST CONTROLS:
TRDAT:
PRETER,EXTTER - specify profile data UFILE (data vs. radius)
PREECF,EXTECF - specify profile data UFILE (ECE data vs. frequency)
  temperature in eV, radii in cm, frequency in GHZ
NLRNTE,PRETET,EXTTET - IF(NLRNTE) specify scalar electron temperature 
data as profile renormalizer vs. time.  Use RMJRTE to specify
renormalization location (more info - TRDAT namelist section).

TRANSP:
NRITER,NSYTER - profile mapping/symmetrization controls
FTEMIN - minimum allowed temperature
4 ION_TEMPERATURE(&neutrons)
See first the section on ION_PWR_BALANCE!

Traditional TRANSP runs solve the ion power balance to predict the
ion temperature.  However, the code may also read ion temperature
scalar or profile data which may be used

  (a) simply to pass through to the plot/postprocessing system
      for comparison with the predicted ion temperature, or
  (b) to drive a feedback loop in which ion conduction is modified
      vs. time to try to follow the specified ion temperature data.
             ...or...
  (c) (new in 1994) ion temperature profile data may be used 
      directly.  Ti is not predicted; instead the power balance
      equation is used to solve for chi(i) (similar to the usual
      treatment of the electron power balance).

In ohmic heating experiments and Hydrogen neutral beam experiments,
neutron data may also be used for the feedback loop (b).  But in
cases where beam-target and/or beam-beam neutrons predominate, 
neutron data should not be used to modify thermal ion conductivity
as the the influence of ion conductivity on neutron production
is insufficient.

In TRANSP, when the ion temperature is predicted, a modified
neoclassical model is employed.  The neoclassical ion conduction
model is modified using an "anomalous multiplier" over which the
user has wide ranging control.  Use of input Ti profile data with
the request to match (NLTI2=.TRUE.) amounts to a request to find
an "anomalous multiplier profile" that causes the predicted Ti
to match the measured Ti.  A refinement on this is to also set
NLTI2TX=.TRUE.; this will cause a multiplier profile to be 
chosen which matches the impurity temperature Tx instead of the
bulk ion temperature Ti -- appropriate if the input data given
is based on an impurity temperature profile measurement.

Alternatively, set NLTIPRO=.TRUE. with NLTI2=.TRUE. to use the
Ti data directly, skipping the predictive calculation.  NLTI2TX
can also be used to specify a Ti-Tx correction.  However:
see the NLTIPRO subtopic.

namelist switches:
TRDAT:
  PRENTX,EXTNTX - specify UFILE of neutrons vs. time, n/sec
  PRETIT,EXTTIT - specify UFILE of ion temperature vs. time, eV
                  only one type of ion temperature data may be read.
  PRETI2,EXTTI2 - 2d UFILE of ion temperature PROFILES vs. time
                  and space.

  Set NLRNTI=.TRUE. to renormalize profile data (PRETI2,EXTTI2) to
time series data (PRETIT,EXTTIT); renormalize at radius RMJRTI or
renormalize the peak value if RMJRTI is defaulted.

TRANSP:
  If reading Ti profile data, set
  NRITI2    to identify spatial coordinate of Ti profile UFILE.
  NSYTI2    to specify symmetrization algorithm.
            see information under DATA_SYMMETRIZATION

  set NLTIPRO=.TRUE. to skip Ti prediction and use Ti data directly.
However, often the Ti data coverage is incomplete.  If Ti data is not
provided (NLTI2=.FALSE.) Ti=factor*Te is used.  See the subtopic.
NEW Feb 1996:  NLTI2TX can now be used with NLTIPRO=.TRUE.

  set NLTI2=.TRUE. to USE Ti profile data to determine a conductivity
multiplier profile to match the measured data in the power balance.

  set NLTI2TX=.TRUE. with NLTI2=.TRUE. to match impurity temperature
Tx instead of bulk ion temperature Ti.
  XTILIM = max (r/a) out to which to try to control the ion 
conductivity (at some radius ion electron coupling overwhelms
conduction in the power balances and the control becomes useless)
  XTIKIM = min (r/a) at which to control the conductivity.  At
r=0 grad(Ti) tends to zero which leads to possible problems in
trying to control conductivity in this region.
  XKFMIN - minimum allowed multiplier on neoclassical ion conduction.
  XKFMAX - maximum allowed multiplier on noeclassical ion conduction.

.................

  NLNTX  must be set .TRUE.  to read in neutron data vs. time.
  (ion temperature will be read if a UFILE is specified.  Difference
  btw. neutrons and Ti is a historical inconsistency).  runs with
  NLNTX=.T have scalar RPLOT function MNEUT (measured neutrons).

..................
  These switches apply if Ti or neutron data vs. time *only* is
  supplied:

  NLFXKF .TRUE. to use TIME SERIES data for feedback control of ion 
    conduction
  IF(NLFXKF) THEN one and only one of the following must be .TRUE.:
    (setting these switches also implicitly describes the UFILE
     ion temperature input data).
    NLTIF0:  make predicted Ti at r=0 match input UFILE data.
    NLTKA:  make predicted Ti profile match K-alpha Ti data.
      specify EEXCKA=excitation energy (eV) for K-alpha simulation.
      see source/balcor/slvtx.for
    NLTXUV:  make predicted Ti profile match UV doppler broadening data
      specify EXIONZ=ionization energy (eV) for measurement simulation.
      see source/balcor/slvtx.for
    NLPCX:  make Ti profile with spectrum to match passive cx data.
      specify NCHPCX=eflux simulation channel no., NSPPCX=eflux species
      number.  See EFLUX_SIMULATION.  Neutral EFLUX simulation controls
      allow specification of fit limits for calculating the ion 
      temperature from the eflux spectrum.  These fit limits can be
      read in as UFILES as fcns of time by setting NLPFIN=.TRUE. and
      defining PREPFL,EXTPFL,PREPFH,EXTPFH in the TRDAT namelist; or
      they may be specified as constants (see controls CXLMLO, CXLMHI,
      chord aiming angles, etc.,under EFLUX_SIMULATION).

    NLTNTX:  adjust Ti conduction to try to match measured neutron flux.

  Controls for the ion temperature feedback scheme:
    Ion conduction is adjusted via a scalar multiplier or anomaly factor
      applied to the neoclassical ion conduction (see ION_PWR_BALANCE).
    XKFMIN - minimum allowed multiplier on neoclassical ion conduction.
    XKFMAX - maximum allowed multiplier on noeclassical ion conduction.
    NTXKF,DTXKF - number and extent of time bins for feedback 
             convolution integral.
    XKGAIN - feedback GAIN control.
    DTCTI - time between calls to readjust ion conduction.
  The feedback algorithm has a "lookahead scheme" to reduce the phase
lag.  see source/balcor/ticomp.for; subroutine TICOMP calls up all ion 
temperature diagnostic simulators and executes feedback instructions.
5 NLTIPRO
The following options were provided by B. Balet of JET -- coded and
tested Nov 1993, installed in PPPL TRANSP, Mar 1994.

===================================================================
  TRANSP DEVELOPMENT : TI *ANALYSIS OPTION* -- B. BALET - NOV 1993
===================================================================
                                                                     
 TRANSP can now be run using Ti in *analysis mode* by setting :
                            
  NLTIPRO = .TRUE. which  1> turns off the Ti predictive model,
                          2> sets Ti from Ti profile provided, or
                          3> if no Ti profile data is provided,
                             assumes Ti = GIEFAC * Te   
                             
 GIEFAC can be a  constant or can vary with time by specifying a 1d
 ufile in the namelist (PREGIE='  ';EXTGIE='  ').
                       
A)  When the *analysis option* is selected , the constraints on 
 the ion heat conductivity (XKFMIN,XKFMAX) do not apply and 
 therefore a hollow Ti profile can be handled by TRANSP (as in 
 the case of pellet injection, for example).
                
B)  When using actual Ti data (rather than Ti=GIEFAC*Te), provision
 is made for the fact that existing Ti measurements do not cover 
 the plasma edge.  The user should set the following namelist items:
                
 -> TIXLIM : max xi (r/a) of validity of the Ti data
 -> TIFACX : edge Ti/Te factor
 -> TIDXSW : switch in a continuous linear way from using Ti data 
             to using TIFACX*Te data over the xi range
                  [TIXLIM,TIXLIM+TIDXSW]
             This is dealt with in subroutine TIEDG.for.  If TIDXSW is
             not set then it is defaulted to 0.05.

 also, for cases where the Ti profile measurement does not reach
 the plasma core:

 -> TIXLIM0 : min xi (r/a) of validity of the Ti data;
              at xi=TIXLIM0, Tdiff = Ti-Te is evaluated.
 -> TIDXSW0 : switch in a continuous linear way to Ti profile
              corrected by TIFACX0*Tdiff, in the xi region
              [TIXLIM0-TIDXSW0,TIXLIM0].
 -> TIFACX0 : for xi.le.(TIXLIM0-TIDXSW0), Ti = Te + TIFACX0*Tdiff.

C)  When using actual Ti data (rather than Ti=GIEFAC*Te), provision
 is made for the fact that existing Ti measurements are available
 only at restricted times (i.e. during neutral beam injection).
 An option for time dependent switching from Ti data to using Te
 for Ti data is set by the user via the namelist variable FIEFAC.
                      
 FIEFAC is constrained between 0.0 and 1.0; this factor can be a
 constant or can vary with time by specifying a 1d ufile in the
 namelist (PREFIE='  ';EXTFIE='  ').  Then, Ti is set according
 to the formula:
             
    Ti(used) = (1 - FIEFAC) * (GIEFAC * Te) + FIEFAC * Ti(data)

  Note that: FIEFAC = 1 gives back the Ti data
             FIEFAC = 0 gives GIEFAC * Te
            
D)  It is possible to switch between Ti *prediction mode* and the
 new Ti *analysis mode* by setting the existing namelist control:
                        
    NKIMODA = 100 <=> 'Ti analysis mode in this time interval'
                                  
 When switching from Ti *prediction mode* to Ti *analysis mode*
 a time lag is needed so that the switchover does not produce a
 discontinuity in Ti.  The user can set the following control: 
                   
    DTISAVE = switchover time interval length (seconds)

 For more information on NKIMODA see 
    TRANSPHELP OPER NAMELIST ION_PWR TIME_VARY
   
E)  New subroutines (in datcor):
             
    PROFTI.for : set Ti in *analysis mode*
    TIEDG.for  : extrapolate Ti at the edge as TIFACX * Te
    TXMJ.for   : set impurity and majority ion temperatures       
                       
F)  default values :
            
    NLTIPRO = .FALSE.; GIEFAC = 1.0; FIEFAC = 1.0; TIXLIM = 1.0;
    TIFACX = 0.0; TIDXSW = 0.0; DTISAVE = 0.01
         
5 NLTI2TX
(new dmc 6 Oct 1994)
(updated 14 Feb 1996 -- see also the SLVTX topic).

if using NLTI2=.TRUE. or NLTIPRO=.TRUE., either directly or 
indirectly as part of a time varying chi(i) model 
(NKIMODA/TKIMOD/XKIMOD), then if

  NLTI2TX=.TRUE.            ! default is .FALSE.

is set, this tells TRANSP to interpret the input Ti profile data 
as impurity ion temperature, not bulk ion temperature, and to
make the appropriate correction (see SLVTX topic).

A new RPLOT multigraph, ITEMP, shows the comparison of the 
impurity temperature TX with the input data TIPRO.

In computing the feedback, the profile Ti-Tx is computed and
smoothed in space.  The namelist parameter

  XTI2TXSM=0.1             ! default is 0.1

controls the amount of smoothing; XTI2XSM expresses a smoothing
radius or half width in normalized flux coordinates.

New Feb 1996:  a time convolution smooth is now also available.
warning:  this causes a time lag.  Controls:

  SLVTXSM=0.05     ! for a 0.05 second trailing triangle
                   ! convolution
  SLVTXS2=[a number btw 0 and 1]
                   ! 0 for unmodified convolution, full time lag
                   ! 1 for full forward extrapolation component
                   !   in convolution; this reduces the time lag
                   !   but also can overshoot
                   ! intermediate values for intermediate results

     time smoothing has breaks at sawtooth/pellet times.

     the implementing code is datcor/smtimtx.for
5 SLVTX

SLVTX upgrade:  D. McCune, Feb 1996.
  See also the NLTI2TX topic.

The SLVTX subroutine of TRANSP (by Steve Scott & Doug McCune)
is an ion power balance post-processing step that estimates the
spread between impurity and main plasma ion species temperatures.

Most of TRANSP treats the ions as all having one temperature, TI.
But in reality auxilliary heating can split the species, e.g.
causing the impurities to have a higher temperature than the
hydrogenic species.  Since the fusion reaction rate is tied to
the hydrogenic species temperatures, but diagnostics usually
see the impurity temperatures, the spread is of interest.

SLVTX takes the ion power balance data developed in the standard
TRANSP ion power balance predictive or analysis model, and 
estimates the temperature spread between impurities and non-
impurity species.  SLVTX produces three output profiles 
(visible in RPLOT multigraph ITEMP):

  TX    -- impurity temperature
  TMJ   -- majority (H/D/T/He3/He4 temperature)
  TIAV  -- (nx*TX + nmj*TMJ)/(nx+nmj) -- average temperature

Generally, SLVTX assumes that the TRANSP TI is TIAV, and evolves
both TX and TMJ, independently, around TIAV.  The exception is
this:  if NLTI2 or NLTIPRO is set and NLTI2TX is *not* set
(i.e. TRANSP is matching Ti to input data without correction)
then the control NSLVTXI should be specified:

  NSLVTXI = 1  ... Ti data is H/D/T/He3/He4 temperature
  NSLVTXI = 2  ... Ti data is average temperature (TIAV)
  NSLVTXI = 3  ... (default) Ti data is impurity temperature

This control affects the SLVTX output.  For example, if NSLVTXI=3,
then TI(TRANSP)=TX is assumed, TMJ is evolved, and TIAV is
computed as the density weighted average.

Generally, the SLVTX outputs are not used but simply output to
RPLOT.

Exceptions:  
  (1)  If NLTI2TX=.TRUE. is set, then a smoothed TIAV-TX
correction is applied to the Ti profile input data which is
assumed to be impurity temperature (see NLTI2TX topic).
  (2)  The switch NLNTMJ can be set:  this has the effect
of using TMJ instead of TRANSP's TI for thermonuclear and
beam-target fusion calculations.  TMJ is smoothed using
the SLVTXSM/SLVTXS2 controls described under the NLTI2TX
topic.

Caveats:
  Although SLVTX numerics have been improved, there can be 
noise in SLVTX output due to noise in the ion power balance
terms themselves (induced e.g. by the Monte Carlo model or
dZeff/dt in the input data).  When using SLVTX with NLTI2TX=T
to correct impurity temperature profile input data, the best
combination of switches appears to be:

  NLTIPRO=T   ! use T(impurity) data directly, no chi(i) feedback
  NLTI2TX=T   ! correct T(impurity) data to give average TI
  [set some smoothing of the TIAV-TX correction term; see
   NLTI2TX topic]

The namelist control TMJTXMAX sets an upper limit on the 
ratios TX/TMJ and TMJ/TX.  Default value is 2.0; this can
be hit when the ion power balance goes wild, e.g. when
TRANSP steps into disruption-affected data.

4 PLASMA_COMPOSITION
Mixed Hydrogen-Helium-Lithium plasmas are now supported, with each
isotope represented as a separate specie, in addition to a single
higher Z impurity specie or multiple impurity species, and various 
fast ion species.

There are new options for controlling the species mixing model --
see the related topic PTCL_BALANCE&neutrals.

Choose subtopic
5 PLASMA
TRANSP permits up to seven thermal ion species, which can be isotopes
of Hydrogen or Helium or Lithium.  Specify:

  NG = initial number of thermal ion species (not counting impurity)
  NGMAX = maximum number (not .gt. 7) of thermal species in run. 
     NG=1, NGMAX=2 specified if the plasma initially is one
     species but neutral beams, pellets, or gas flow introduce a 
     2nd species.

  for species j, j=1 to NGMAX, 

  APLASM(j) = atomic weight of jth ion species

  BACKZ(j) specifies the charge of the jth species.  Legal values 
    are 1.0 or 2.0 or 3.0 for Hydrogen Helium or Lithium isotopes.

For information on how to initialize the mix of plasma gasses and
how to control the evolution of the mix -- see the related topic
PTCL_BALANCE&neutrals.
                    
NOTE: in TRANSP the atomic weight (A) is defined in terms of
of proton mass:  A = m/mp; H nucleus (p) to have A=1.00000. But if
input data uses the chemistry definition where AMU is the average mass per 
nucleon over common atomic species (in this definition H has A=1.0079),
then AMU inputs will be divided by 1.0079 to get normalization 
to proton mass, A=m/mp. Such a correction will be done for all species:
for background plasma, for impurities, for beam species, for fusion products, 
for CX species in eflux calculation and for CX sight-line, 
for RF minority, for pellet. For tokamakium impurity, user's inputs will 
be left as they are, but if the user supplies a list of real impurity 
species their masses will be corrected.
                   

5 IMPURITY
The original TRANSP model employed a single fully stripped light 
model impurity specie.  This still exists and is described below.
In addition, there is a multiple impurity option available when
profile data of the multiple impurities is available over time.
Impurities AMU will be normalized to proton mass, for details see (5) Plasma.

6 Single_Impurity_Model
enter via namelist:
  AIMP = atomic weight of impurity (e.g Oxygen=16.0)
  XZIMP = charge of impurity ion (e.g. Oxygen=8.0)

THESE ARE THE ONLY AVAILABLE CONTROLS on the impurity species itself.
impurity density will be determined by simultaneous solution of the
Zeff and quasi-neutrality equations with Zeff and electron density as
input, impurity density and (summed) hydrogenic ion density as output.

See also the section on ZEFF.

New Feature:  March 1994 at PPPL:  Implemented and tested Nov. 1993
by Pam Stubberfield of JET:

  XZIMP can be made a function of time by specifying an input Ufile
  containing the time variation of Zimp -- set namelist controls 
     PREZIM, EXTZIM
  to name the Ufile.  See NOTE, below.

  This introduces a d(Zimp)/dt term in the impurity particle balance.

  If this feature is used, Aimp=2.0*xZimp is enforced at all times.

NOTE -- if Zimp vs. time is used, then also set

     NMSIGX=2

to get the newer impurity stopping cross section (used in beam
deposition and thermal neutral transport calculations).  The old
NMSIGX=1 model implementation, based on Olson et al, P.R.L. 41,
num. 3, p. 163 cross section, assumes Zimp does not vary in time.

The NMSIGX=2 model for impurity stopping is based on interpolation
of Carbon and Oxygen cross sections from ORNL-6090/V5, Atomic Data
for Fusion, Vol. 5, "Collisions of Carbon and Oxygen Ions with
Electrons, H, H2, and He", R.A. Phaneuf, R.K. Janev, M.S. Pindzola.
With this data the Zimp may vary in time; also if Zimp<6 or Zimp>8
the impurity stopping cross sections will be scaled appropriately.

The NMSIGX=2 model is newer than NMSIGX=1 and based on more recent
data, and is somewhat different.  NMSIGX=1 remains the default in
TRANSP, to avoid changing reruns of old runs.  If the effect of
impurities on beam deposition is important in a case being rerun,
you may want to first rerun with NMSIGX=2 before putting in Zimp
vs. time data, in order to assess the effect of the updated
impurity cross section on your run results.

All species AMU will be normalized to proton mass, for details see (5) Plasma.

6 Multiple_Impurities
Transp has the capability for including multiple impurities in the 
analysis when supplied with the impurity profiles over time.  The 
impurity data can be used in the calculation of Zeff using the NLZSIM 
or NZEFMOD transp namelist variables. Even if Zeff is computed by 
another method, the impurity data is used throughout the run to scale 
the impurity densities so the relative fractions of the impurities are 
representative of the data.  While most of the impurity computations 
are still based on the total impurity density RHI, the average impurity 
charge and atomic weight will now have a temporal and radial dependence.
(see multiple_impurities.doc for more info)

All species AMU will be normalized to proton mass, for details see (5) Plasma.

7 Usage
General
-------
Multiple impurity namelist data is specified through arrays indexed by the
multiple impurity element index.  To specify a Ufile as a source
of multiple impurity data, the PRESIM(I),EXTSIM(I) variables should
be set for each impurity element 'I'.  Alternatively/additionally, the 
impurity density for element I can be set as a fraction of the electron 
density by using the namelist variables DENSIM(I) and/or DENSIMA(I). 
These controls can be mixed, the interpretation is summarized in this
table, for element (I); here ne = electron density and nx = element 
impurity density summed over all charge states:

  PRESIM,EXTSIM only -- actual density profile, #/cm3
  PRESIM,EXTSIM & DENSIM -- profile renorm, nx/ne = DENSIM @ axis
  PRESIM,EXTSIM & DENSIMA -- profile renorm, nx/ne = DENSIMA @ edge
  PRESIM,EXTSIM,DENSIM,DENSIMA -- sliding linear renorm from axis to edge

  DENSIM only -- nx/ne = DENSIM everywhere
  DENSIMA only -- nx/ne = DENSIMA everywhere
  DENSIM & DENSIMA -- nx/ne = DENSIM + f(x)*(DENSIMA-DENSIM) 
     with f(x) = x**XZFA1 * (1 + (XZFA2-XZFA1)*(x-1))
     which satisfies   f(0)=0, f'(0)=0 for XZFA1 > 1
                       f(1)=1, f'(1)=XZFA2
     default values are: XZFA1=2, XZFA2=0

If none of these controls are set, then, the original single impurity 
transp model is used.

The number of available impurity elements is preset by the MIMPS 
parameter (currently 8) in the file $CODESYSDIR/source/misc/trdatgen.spec.
The total number of distinct element and charge states is set by the 
IMPT parameter (currently 300).

Data File Input
---------------
The SIM trigraph uses the 3d profile capability in the trdatgen code 
generator.  This is a new capability of TRDAT which allows a single 
trigraph to read in multiple sets of profile data.  The namelist variables 
used to specify the data files and options under the SIM 3d trigraph 
are arrays.  The outer index of the array is the index of the impurity 
element for the data.  As an example of specifying the data under the 
TRDAT namelist,

  PRESIM = 'N', 'N'
  EXTSIM = 'DEMO_8_16', 'DEMO_9_18'

In this case transp will attempt to read in two Ufiles for two impurity 
elements.  Each element can have one or more charge states depending on
the data with one profile for each charge state.  Similarly, the NRISIM, 
NSYSIM, ... arrays are available for further defining the profile data.  
Unlike PRESIM and EXTSIM, the integer and floating point SIM options have 
the characteristic that the last value in the array will be applied to 
all the following elements. For example, specifying

  NRISIM = 5, 3

is equivalent to

  NRISIM = 5, 3, 3, 3, 3

The atomic weight and atomic number of the elements can be specified in
either the transp namelist arrays AIMPS and XZIMPS,
  AIMPS = 16, 18
  XZIMPS = 8, 9
or in scalar variables A and Z in the Ufiles.

The profile data in the Ufiles can have the format,
  1d Ufile -> one charge state for this element with a constant profile 
              over all time -- the atomic number is used as the charge
              Ufile axis: [x]
  2d Ufile -> one charge state for this element with a time varying 
              profile -- the atomic number is used as the charge
              Ufile axis: [x,t] or [t,x] (lfixup may be required)
  3d Ufile -> multiple charge states for this element with time varying 
              profiles -- the third coordinate of the 3d Ufile data will be 
              the charge associated with that charge state profile
              Ufile axis: [x,t,charge] or [t,x,charge] (lfixup may 
                          be required)

DENSIM
------
DENSIM is used to set the impurity data as a fraction of the current
electron density as an alternative to using the PRESIM,EXTSIM data file
method.  By itself

  DENSIM(2) = .01   ! means: set impurity element 2 to be 1/100 of RHOEL

As outlined above, DENSIM and PRESIM/EXTSIM can now be mixed.  For elements
where PRESIM/EXTSIM are omitted, or, the indicated Ufile lacks Z & A data,
the atomic number and weight for the element must be set in the namelist 
using the AIMPS and XZIMPS arrays.

By default, DENSIM(I) = -1, which means, "inactive";

DENSIMA(I) (for edge oriented renormalization) behaves similarly; its 
default value is also -1, meaning "inactive".

Coronal Equilibrium
-------------------
The charge states associated with an impurity species is usually derived from
the SIM input file.  However, the charge states can be redistributed according
to the coronal equilibrium as appropriate for the current time step's electron 
density and temperature.  The NADVSIM(I) namelist variable controls this for 
each impurity element.
  NADVSIM(I) = 1     ! redistribute the charge states to satisfy the
                     ! coronal equilibrium
             = 0     ! do not modify the charge state distribution

[as of Dec2002, neutrals are no longer included in the coronal equilibrium]

Note: The default for NADVSIM is 
   0 -> for elements with PRESIM/EXTSIM ufile data
   1 -> for elements controlled by DENSIM(I) and/or DENSIMA(I)

Restricting Output
------------------
The XIMS rplot label is used to examine the individual charge state densities
of one particular element.  However, rplot is limited to 15 plots per graph.
TRANSP will limit the number of charge state species output to satisfy this by
attempting to select a relatively uniform distribution of charge states for
each element.  The NINCSIM(3,I) namelist variable gives the user some control
for choosing the charge states output for element I,
  NINCSIM(1,I) = lower limit of charge states to output (default 0)
  NINCSIM(2,I) = upper limit of charge states to output (default atomic Z)
  NINCSIM(3,I) = if >0  -> stride -- fixed offset between charge states
                 if <=0 -> auto, a relatively uniform distribution of 
                           charge states will be used (default)

Other
-----
There are a couple of other transp namelist controls associated with 
multiple impurities,

  NLZSIM -> LOGICAL, if this is true, Zeff will be set for each radial 
            zone based on the multiple impurity data as described above.

  NLMINSV -> LOGICAL, if .true., neutral beam interaction with 
             impurities will be computed for each impurity separately 
             and combined.  if .false., the neutral beam interaction 
             with impurities will be based on a composite impurity 
             density with an averaged charge and atomic weight (see 
             source/nubeam/nbatom).  This option is .true. by default.

  NCMULTI -> selects how the NCLASS neoclassical analysis deals with
             multiple impurities -- see the NCLASS_neoclassical section

7 Warning
The level of impurities is often set in TRANSP by specifying Zeff through
visible brehmsstralung data.  The magnitude of the impurity density in Ufile
data would not be important because it would end up being rescaled anyway.
This is still true.  If only DENSIM (or DENSIMA) is used to define the 
impurities then the magnitude of the impurities is fixed by Zeff, the charge 
state distribution is fixed by the coronal equilibrium (because NADVSIM(I)=1 
automatically for DENSIM(I) only elements) and DENSIM only represents the 
relative ratio between impurity elements.  BUT, if PRESIM,EXTSIM only 
Ufile data is MIXED with DENSIM only impurity elements, then, the absolute 
magnitudes between the Ufiles and DENSIM values become important.  In this 
case it is important to remember that DENSIM represents the magnitude of 
the impurity as a fraction of the electron density whereas the Ufile 
contains absolute density data.

7 Restrictions
 - The use of SIM input data is not allowed with the ZIM option
   (i.e. Zimp(t) Ufile data is not allowed).
 - XSRCIM = 0. is required (will be changed for you if nonzero)
 - NMSIGX = 2  is required (will be changed for you if not 2)
 - the atomic number and weight must be set in either the transp
   namelist or the Ufile.  The atomic number and weight of DENSIM/DENSIMA
   only densities must be set in the namelist.
 - PRESIM(I),EXTSIM(I) elements must come before DENSIM(I) only 
   elements, with respect to multiple impurity index 'I'. 

7 Updatability
DENSIM and DENSIMA can be modified on namelist updates, but some 
restrictions are necessary to assure well behaved time interpolations:

  (a) the transition time from old to new values is set by DTZEFMOD(1)
      so that the evolution of the density profile remains continuous;
  (b) if DENSIM(I) < 0 originally, then DENSIM(I) < 0 must remain on update;
  (c) if DENSIMA(I)< 0 originally, then DENSIMA(I)< 0 must remain on update;
  (d) if DENSIM(I) >=0 originally, then DENSIM(I) >=0 must remain on update;
  (e) if DENSIMA(I)>=0 originally, then DENSIMA(I)>=0 must remain on update.

In other words, the renormalization values can be updated but the basic
logic for renormalization (at axis, at edge, or in both places) must not 
change with an update.  This is enforced in trcore/datchk_update.f90.

7 Rplot_Output
The impurity data as read from the Ufiles is stored in rplot names
beginning with SIM.  The SIM name for the raw input data includes 
an index corresponding to the array index from the PRESIM,EXTSIM arrays.  
The impurity data as used in the program is stored in rplot names 
beginning with NIMP.  Multigraphs between the SIM and NIMP data can 
be found in rplot names beginning with XIM.  The names for the NIMP,
XIM and processed SIM data are based on the periodic table symbol for 
the element and on the charge state.  The composite impurity density
for all the charge states for an element is stored in rplot names 
beginning with NIMPS.  Multigraphs between the individual charge 
states and the composite impurity density for an element are stored 
in rplot names beginning with XIMS.  The multigraph XDENS includes 
the total impurity density as used in the program, NIMP, as read 
in from the data files, SIMDATA and the individual impurity densities
from each of the elements NIMPS_**.

The average impurity charge and atomic weight over the plasma
is contained in XZIMP and AIMP.  Profiles of the average impurity 
charge and atomic weight are contained in XZIMPJ and AIMPJ.

Some examples:
  SIMDATA    TOTAL MULT. IMPURITY INPUT       N/CM**3
  SIM_F_9    F+9 Impurity Density Input       N/CM**3
  SIM_IN_1   SIM[1] data as input             n/cm**3
  SIM_IN_2   SIM[2] data as input             n/cm**3
  SIM_O_8    O+8 Impurity Density Input       N/CM**3
  SIM_USE_1  SIM[1] data as used              n/cm**3
  SIM_USE_2  SIM[2] data as used              n/cm**3

  NIMP       TOTAL IMPURITY DENSITY           N/CM**3
  NIMP_F_9   F+9 Impurity Density             N/CM**3
  NIMP_O_8   O+8 Impurity Density             N/CM**3

  NIMPS_C    C Total Impurity Density         N/CM**3

  >XIM_F_9     is "Impurity Density for F+9         " in N/CM**3
    1. +("NIMP_F_9  ")   F+9 Impurity Density
    2. +("SIM_F_9   ")   F+9 Impurity Density Input

  >XIM_O_8     is "Impurity Density for O+8         " in N/CM**3
    1. +("NIMP_O_8  ")   O+8 Impurity Density
    2. +("SIM_O_8   ")   O+8 Impurity Density Input

  >XIMS_C      is "Impurity Density for C           " in N/CM**3
    1. +("NIMP_C_1  ")   C+1 Impurity Density
    2. +("NIMP_C_3  ")   C+3 Impurity Density
    3. +("NIMP_C_5  ")   C+5 Impurity Density
    4. +("NIMP_C    ")   C Total Impurity Density

  >ZIMP      is "Average Mult. Impurity Z           " in
        1. +("XZIMPJ    ")  Zonal Avg Z of Impurity
        2. +("ZIMPS_B   ")  B Avg Mult. Impurity Z
        3. +("ZIMPS_BE  ")  Be Avg Mult. Impurity Z

7 Example
This is a fictitious example of the use of the DENSIM namelist variable
for specifying the impurities without the use of PRESIM,EXTSIM Ufile input.
Zeff is set through visible brehmsstrahlung data so the DENSIM magnitudes
are not important in this case (though see warning above).  Three elements
are given (nickel, oxygen and carbon) in the ratios 1:2:4.  The coronal
equilibrium is used for the charge states.  Because nickel has too many
charge states to fit in the XIMS_NI rplot multigraph, the default would be to
output every other charge state.  The NINCSIM(1,1) variable sets the initial
charge state to output as 15 so the most stripped species will show up
in XIMS_NI.

  ...
  NLVISB=.true.    !* SET .TRUE. TO READ VIS. BREMS. DATA
  NLZVBR=.T        !* SET .TRUE. TO USE VIS. BREMS. DATA FOR ZEFF
  
  DENSIM = .01, .02, .04        ! density Nx(i) = DENSIM(i) * Ne(i)  before 
                                ! Zeff scaling
  XZIMPS = 28, 6, 8             ! atomic numbers
  AIMPS  = 58.69, 12.01, 16.0   ! atomic weights

  NADVSIM = 1, 1, 1   ! redundant -- this is the default for DENSIM elements
  NINCSIM(1,1) = 15   ! look at charge states 15,16,...,28 for nickel, use
                      ! default for carbon and oxygen
  ...

Some worthwhile multigraphs to look at for this data are: 
  XIMS_NI, XIMS_C, XIMS_O, XDENS, PBOLOS, ZIMP

7 MDSplus_access
(Copied from email to MIT TRANSP Users, 20 Nov. 2007 -- DMC).

Hi Bill and Catherine,

This message is in reference to recent TRDAT-crashed CMod runs 2204, 2205, 
and 2206 (PPPL IDs), where the intention is to input impurity density 
profile data through the "SIM" channel via MDS+.

Background information: usually, the MDS+ TRANSP tree (input data subtree)
node names must match the "trigraph" channel names used in the TRANSP code-- 
e.g. "NER" for electron density, "TER" for electron temperature.  There is 
a practice of setting the namelist variables PRExxx, EXTxxx (e.g. PRENER, 
EXTNER) which historically indicated filename prefixes and suffixes, for 
the older "Ufiles" based TRANSP data input mechanism.  In the context of 
MDS+ input, the setting of these variables merely indicates the presence 
of MDS+ data to be read, not the node name from which the data is provided.
I.e.:

  PRENER='P'
  EXTNER='NER'

...means, read the NER data from the NER MDS+ tree node.  (The prefix and
suffix values are only used to form a filename for Ufiles *output* if a
separate namelist option is set ("SCLREQ(1)='$UFCOPY'"); this allows Ufiles
input datasets to be formed from MDS+ input tree data, frequently useful
here for data capture for debugging).  If one had set "EXTNER='NER2'" 
instead, there would be no change in the ability of the run to find the 
input data at MDS+ node "NER"-- it would still be read from the same 
NER node of the MDS+ tree; if Ufiles output were activated trdat would 
write to a differently named Ufile with extension ".NER2" instead of ".NER".

BUT... SIM is different.  This is because the channel supports not one 
input signal but multiple signals corresponding to multiple impurities.  
In this case, CHARACTER*nn namelist items PRESIM and EXTSIM are arrays, 
not scalars, and, the following MDS+ node names must be used:

  SIM01 for the first impurity (PRESIM(1),EXTSIM(1))
  SIM02 for the 2nd impurity   (PRESIM(2),EXTSIM(2))
  SIM03 for the 3rd impurity   (PRESIM(3),EXTSIM(3))
     ...etc... (up to 8 impurities)

Also, the SIMnn data can be 3d signals vs. (t,[charge state #],x), or, 2d 
signals vs. (t,x) (the latter interpreted either as the total density of 
the impurity summed over all charge states, or, the density of the fully 
stripped charge state of the impurity, depending on namelist switches... 
I think... Rob Andre could verify).

In the case of CMOD 2206, I made a temporary debug version of TRDAT that
was able to use the EXTSIM(1) value instead of SIM01 for the MDS+ node 
name, and so was able to read the data-- it was 2d vs. (t,x).  It failed 
further on, however, because it is also necessary, as is the case for all
inputs, to specify to TRDAT the type of radial coordinate.  A correct 
setting would be:

  NRISIM(1)=-4

(Similar to all your other profile inputs-- this specifies a normalized
radial flux coordinate).

With this added to your 2206 namelist, I was able to see your data-- in 
TRDAT plotting routines-- the data looked OK.

Now, there are scalar values that can be attached to each SIMnn signal 
to indicate the A and Z of the impurity for which data is provided.  If 
this is not found, the code uses AIMPS(nn),XZIMPS(nn) for the SIMnn 
A & Z values, from the namelist.

To summarize:  Please put your density data in MDS+ nodes:

  SIM01 for your first impurity density
  SIM02 for your 2nd impurity density
     --etc--

Please set NRISIM(nn)=-4 for each SIMnn input signal, to indicate that
the data is to be read in vs. a normalized radial flux coordinate.  Set 
AIMPS(nn) and XZIMPS(nn) in the namelist to specify which impurity species 
is being described by the SIMnn data.

Note that you can still have Zeff data specified from another source, and
have the impurity density profiles renormalized to match this... there 
are various options for this; see TRANSP HELP.  People have used this in 
the past when they had multiple impurity density profiles that were 
relative to each other and gave relative radial variations but were not 
absolutely calibrated.

For now, I deleted your TRDAT-crashed runs from the PPPL system.

Regards & Happy Thanksgiving,...

   -----------Doug
   Doug McCune, co-head, PPPL Computational Plasma Physics Group
   & TRANSP group leader

7 Summary_on_multiple_impurities

for each element (I):

AIMPS, XZIMPS  --  A & Z of impurity element (default: unspecified).
               (can be set from scalars in PRESIM/EXTSIM Ufile data).
PRESIM/EXTSIM  --  select absolute density profile from Ufile data
               (NRISYM & NSYSIM select radial coordinate & symmetrization)
               (default: unspecified).
DENSIM -- nx/ne on axis (or everywhere if DENSIMA not set).
               (default: not set; use PRESIM/EXTSIM).
               (if set with PRESIM/EXTSIM: renormalize the profile data).
DENSIMA-- nx/ne at edge (or everywhere if DENSIM not set).
               (default: not set; use PRESIM/EXTSIM).
               (if set with PRESIM/EXTSIM: renormalize the profile data).
NADVSIM -- =1 to set charge state densities from coronal equilibrium
               (=0: use PRESIM/EXTSIM data to set charge states).
               (if no PRESIM/EXTSIM data, =1 is forced).

nx = impurity density summed over charge states
ne = electron density

For each species (with non-zero AIMPS & XZIMPS) a data source must be
specified.  If there are N impurity species but M<N PRESIM/EXTSIM files,
these must be used for impurity species indices 1:M; M+1:N would be set
by DENSIM and/or DENSIMA.

If Zeff input data is provided from another source, i.e. not set from
the multiple impurity density data, the entire set of impurity density
data will be renormalized to be consistent with this Zeff data.

Use NLZSIM=.TRUE. to specify that Zeff is to be set from the multiple
impurity density data.

5 Other_species
If there is only one beam species and it is an isotope of hydrogen,
its atomic weight is specified in the namelist control ABEAM.

If there are more than one beam species or there are Helium beams,
ABEAMA(ib) and XZBEAMA(ib) specify the A and Z of the ib'th beam
source.  See info on NEUTRAL_BEAMS.

XZMINI, AMINI specify non-thermal "minority species" for ICRF
heating (there can be more than one minority specie).

APEL (and optionally APEL2) specify pellet species (see information
on PELLETS).

All species AMU will be normalized to proton mass, for details see (5) Plasma.


4 ZEFF
In TRANSP there are TWO definitions of Zeff:
  1)  Plasma compostion Zeff
      ne*Zeff= sum[j](nj*Zj**2)
      which determines the impurity concentration and hydrogenic
      ion depletion factor
  2)  Resistivy Zeff or "MAGDIF" Zeff
      a parameter in the Spitzer and or neoclassical resistivity
      evaluated in source/magcor/resis.for and used in solving the 
      poloidal field diffusion equation.
The presence of these two Zeff definitions in the code must be born
clearly in mind to understand what follows.

Note -- if the poloidal field (q profile or current profile) is 
obtained from measurements rather than using the predictive model,
then Resistivity Zeff is not available.

TRANSP may obtain plasma composition Zeff from any of the following
sources (cf source/datcor/gzeff.for):
  1)  set to a constant by namelist input
  2)  flat profile assumed, time dependent value read directly from
      1d Zeff UFILE
  2A) analytic profile shape assumed, time dependent value for Zeff
      on axis read from 1d Ufile; time dependent value for Zeff at
      plasma boundary read from Ufile.
  3)  as 2) but UFILE contains time dependent chord integral Visible
      Bremsstrahlung data which is converted by TRANSP.
  3A) as 2A) but the central value is determined by chord integral
      Visible Bremsstrahlung data converted by TRANSP.
  4)  2d UFILE of Zeff vs. time and radius is input.
  5)  2d UFILE of Visible Bremsstrahlung local emmisivities is input
      and converted to local Zeff vs time and radius in TRANSP.
  6)  plasma composition Zeff set to a fixed multiple of resistivity
      Zeff output by the poloidal field solver.
  7)  Zeff profile derived from impurity density input data.
  8)  as 7) but density data is renormalized to match input
      chordal VB data.

The Zeff data source can be made to vary in time.  See the subtopic
on plasma composition Zeff.

TRANSP may obtain resistivity Zeff from any of the following sources
(cf source/magcor/czeff.for):
  1)  feedback loop to adjust Zeff to get a resistivity which results
      in predicted plasma surface voltage matching UFILE input surface
      voltage data, or
  2)  direct namelist control (independent of plasma composition Zeff),
      or
  3)  set to fixed multiple of plasma composition Zeff.

options 2 and 3 involve solution of the poloidal field equation with
"floating" (i.e. unconstrained) surface voltage.  For more information
see the MAGNETICS topic under NAMELIST.

specific namelist switch settings under subtopics...
5 Plasma_comp_Zeff
TRDAT UFILES:  (VB = VISIBLE BREMSSTRAHLUNG)
  PREZEF,EXTZEF - prefix and extension name UFILE Zeff vs. time only.
  PREVSB,EXTVSB - ditto name UFILE of chord integral VB light vs. time
  PREZFA,EXTZFA - ditto name UFILE of Zeff at edge vs. time
    can be used with PREZEF/EXTZEF data or with chordal VB data.
  PREZF2,EXTZF2 - ditto name UFILE of Zeff vs. time and space.
    set NRIZF2, NSYZF2 to specify spatial coordinate definition and
    symmetrization option-- see section on DATA_SYMMETRIZATION.
  PREVB2,EXTVB2 - ditto name UFILE of VB EMMISIVITY (NOT CHORD 
    INTEGRAL, MUST HAVE BEEN ABEL INVERTED) vs. time and space.
    set NRIVB2, NSYVB2 to specify spatial coordinate definition and
    symmetrization option-- see section on DATA_SYMMETRIZATION.
  PRENIM,EXTNIM - ditto name UFILE of impurity density vs. time
    and space; set NRINIM and NSYNIM to specify the spatial
    coordinate definition and symmetrization option.  The
    impurity density is taken to have a Z if XZIMP, as specified
    in the namelist or by 1d Ufile vs. time input.  This data
    is converted to Zeff internally in TRANSP.  It may optionally
    be scaled to match VB chord integral data.
  PRESIM,EXTSIM - arrays of prefix and extensions for the names
    of the Ufiles containing impurity density vs. times data for 
    use with multiple impurities.  If the impurity data is
    not used for Zeff, it will still be used for computing the
    relative fractions of each impurity and a radially dependent
    impurity Z and A (see Multiple Impurities below).  The maximum
    number of Ufiles is set by the parameter IMPS (currently 5).

TRANSP SWITCHES:  (implemented in TRDAT and source/datcor/gzeff.for):
at most ONE SOURCE of Zeff should be specified:

NLZEFM - .TRUE. to use RESISTIVITY ZEFF for PLASMA COMPOSITION
  set CZEFFM (default CZEFFM=1.0) to get 
  PLASMA COMP ZEFF = CZEFFM * RESISTIVITY ZEFF
NLZFIN - .TRUE. to read and use 1d UFILE of Zeff vs. time
NLZFI2 - .TRUE. to read and use 2d UFILE of Zeff vs. time and radius.
NLZFXI - .TRUE. to read and use 2d Ufile of single impurity ion density
      vs. time and radius.  may use with VB chordal data...
NLZSIM - .TRUE. to use multiple impurity data -- may use with VB
      chordal data ...
NLVISB - .TRUE. to read 1d UFILE of VB chordal data
-->  set NLZVBR .TRUE. to USE this data in TRANSP for plasma comp.
      Zeff; otherwise data is just passed through for plotting.
-->  NLVISB.AND.NLZVBR.AND.NLZEFA may be combined; then the edge
      Zeff is fixed by the input data and the central Zeff is
      found which matches the VB data.
-->  NLVISB.AND.NLZVBR.AND.NLZFXI may be combined; then the 
      impurity density profile input is renormalized to match
      the chordal VB data.
NLVB2 - .TRUE. to read 2d UFILE of VB emmisivity data vs. time and
  minor radius.
-->  set NLZVB2 .TRUE. to USE the VB2 data for plasma composition
  Zeff.
NLZEFA - .TRUE. to use ZFA data (edge Zeff data vs. time or namelist
  value XZEFFAI for constant edge Zeff if Ufile data is unavailable).
--> must be used with NLZFIN=.TRUE. or NLVISB.AND.NLZVBR=.TRUE.
  The Zeff profile will be:

    Zeff(x) = Zeff0 + (Zeffa-Zeff0)*f(x)
    f(x) = x**XZFA1 * [1 + (XZFA2-XZFA1)*(x-1)]

  where x=flux surface label =~ r/a, and XZFA1 and XZFA2 control
  the profile shape.  XZFA1.gt.0 is required.  If XZFA1.gt.1, then
  the conditions

     f(0)=0   f'(0)=0   f(1)=1  f'(1)=XZFA2

  are satisfied.  The defaults are XZFA1=2.0, XZFA2=0.0.

  If this is used with NLZFIN, the ZEF Ufile specifies Zeff0.

  If this is used with NLVISB.AND.NLZVBR, TRANSP will try to find
  a Zeff0 btw 1.0 and Zimp that matches the VB data.  The Zeff0
  could end up pinned to one of the extrema.

**> more info on VB in the subkey

**> see VB simulation subroutine source/datcor/visbrm.for.  In TRANSP GZEFF
subroutine, if VB data is used, VISBRM is called to evaluate expected
emmision if Zeff=1.0.  Ratio of actual data to this evaluation yields
Zeff to be used.

IF NONE of the above sources of Zeff data is specified, 
  namelist scalar XZEFFI specifies the value (independent of time and
radius) to be emploryed.

CONSTRAINTS on ZEFF:  Zeff must allow a non-negative impurity density
and a positive THERMAL hydrogenic ion density when the quasi-neutral-
ity and Zeff equations are jointly solved.  Thus 1.0 is a lower bound
and XZIMP (impurity Z -- in the case of multiple impurities, this is
computed from the input data) is an upper bound.  Furthermore if there is
fast ion density and this density approaches the electron density,
then Zeff must tend towards unity.  The GZEFF routine enforces these 
constraints.
6 time_switching
New DMC Feb 1995

The source of plasma composition Zeff may now be switched time
dependently in TRANSP.

Set

  NZEFMOD=N1,N2,N3,...  (up to 8 values, explained below)
  DTZEFMOD=DT1,DT2,...  (up to 7 values, all positive)
  TZEFMOD=T1,T2,...     (up to 7 values, T1 < T1+DT1 < T2 ...)

(defaults:  NZEFMOD(i) not specified, TZEFMOD(i)=+infinity, 
            DTZEFMOD(i)=0.01 seconds)

The NZEFMOD values specify which Zeff data source to use during
which time interval:

  N1  specifies the data source from t = -infinity to t=T1
  N2  specifies the data source from t = T1 to t = T2
      ..etc..

Since Zeff is a state variable and must be continuous in a
TRANSP run, DT1 specifies a time for "phasing over" from
the N1 to the N2 data source, DT2 for "phasing over" from
N2 to N3, etc.

The Nj can have any of the following values:

  -1 -- using the old data, freeze Zeff in time (not valid 
        for N1).
   0 -- flat Zeff vs. r, use the namelist input XZEFFI
   1 -- use the resistivity Zeff (can be flat or profile,
        as per resistivity Zeff options; resistivity Zeff
        must be independently specified).  (NLZEFM=.T).
   2 -- flat Zeff, use Zeff(t) input data (NLZFIN=.T).
   3 -- Zeff profile, use Zeff(r,t) input data (NLZFI2=.T).
   4 -- flat Zeff, use chordal VB data (NLZVBR=.T).
   5 -- Zeff profile, use VB profile data (NLZVB2=.T).
   6 -- Zeff profile, use single impurity density data (NLZFXI=.T)
   7 -- analytic Zeff profile, using edge and center data,
        NLZFIN.AND.NLZEFA = .T
   8 -- analytic Zeff profile, using edge and chordal VB
        data, NLZVBR.AND.NLZEFA = .T
   9 -- Zeff profile, single impurity density renormalized to 
        chordal VB data, NLZFXI.AND.NLZVBR = .T
   10 - Zeff is computed from multiple impurities (NLZSIM=.T)
   11 - Zeff is computed from multiple impurity data
        as scaled by chordal VB data (NLZSIM=.T .and. NLZVBR=.T)

The use of various Nj values implies the presence of Ufile
data.  An error will result if the Ufile data is missing.

Example:

  NZEFMOD=4,9,4          ! 3 values
  DTZEFMOD=0.02,0.02     ! 2 values
  TZEFMOD=4.0,5.0        ! 2 values

Meaning:

  before 4 seconds, VB data is used to calibrate a flat
    Zeff profile
  between 4 and 5 seconds, VB data is used to renormalize
    an impurity density profile.  A 20 msec phase-in time
    is allowed.
  from 5 seconds on, we are back to VB data used to 
    calibrate a flat Zeff profile.  A 20 msec phase-in
    time is allowed.

6 VB_info
New Aug 1986 documentation...

When using chordal input VB, i.e. NLVISB=.TRUE. (and possibly 
NLZVBR=.TRUE. to control the plasma composition Zeff with
this data), the following additional controls are available:

RVISB  -  radius of start pt of VB chord (cm)
YVISB  -  elevation of start pt of VB chord (cm)
THVISB -  poloidal aiming angle (degrees) of the chord
          positive angle aims "up"
PHVISB -  toroidal aiming angle (degrees) of chord.

(THVISB=PHVISB=0.0 means a chord looking directly in towards
the machine centerline from an outside, large major radius
position).

These controls allow use of chordal data which miss the plasma 
axis or do not enter the plasma perpendicularly.  If RVISB=0.0
(default) is left, the old perpendicular chord thru the ctr of
the plasma assumption applies.

The following "Gaunt factor" namelist controls have been added:
VBGF0, VBGFZ, VBGFT-- for more information see source/datcor/visbrm.for

The Gaunt factor controls have an effect whether using chordal or
profile VB input data.  An attempt has been made to choose 
reasonable default values for these parameters.

5 Resistivity_Zeff
if SURFACE VOLTAGE data is read in from a 1d UFILE vs. time, that
data may be used in a feedback loop in the poloidal field equation
solver to predict Zeff as a function of time.  SET:
TRDAT:  PREVSF,EXTVSF:  voltage UFILE name
TRANSP:
  NLMDIF = .TRUE. (this is the default) 
  NLSPIZ = .TRUE. or .FALSE. (for Spitzer or Neoclassical resistivity)
  NLPCUR = .TRUE. (this is the default) to match plasma current.
  NLVSUR = .TRUE. to find a Zeff which results in a resistivity
           profile such that when the poloidal field equation is
           solved (matching the plasma current data precisely),
           the correct (measured) surface voltage is also obtained.
  normally Zeff is then assumed to be independent of radius.  However,
  a profile shape may be introduced by setting the exponent XPZEFF.
  see source/magcor/czeff.for, the routine which sets the resistivity 
  Zeff profile.

There are two options for the shape of the resistivity Zeff profile:

NLZFIM=.FALSE. (default):  use the plasma composition Zeff.
  if this option is taken, the plasma composition Zeff cannot
  be set from resistivity Zeff, and the resistivity Zeff profile
  controls (XPZEFF, XPZEFRAT) should not be set.

  if NLVSUR is .TRUE., the resistivity Zeff will be proportional
    to the plasma composition Zeff at the level necessary to
    achieve match up with the surface voltage data.
  if NLVSUR is .FALSE., then the formula used is
    resistivity Zeff  =  (plasma comp. Zeff) / CZEFFM,
    where CZEFFM (default 1.0) is set in the namelist.

NLZFIM=.TRUE.:  specify the resistivity Zeff profile shape:

  XPZEFRAT = (Zeff(edge)-1)/(Zeff(ctr)-1)  ... edge ratio
    default value is 1.0 for flat Zeff profile.
  XPZEFF = shape exponent, default is 0.0 for flat profile:

    for normalized radial coordinate x, 

    Zeff(x) = Zeff(edge)+(Zeff(ctr)-Zeff(edge))*(1-x**2)**XPZEFF

    where Zeff(ctr) set as follows:

  if NLVSUR is .TRUE., the resistivity Zeff level will be 
    adjusted as necessary to achieve match up with the surface
    voltage data;
  if NLVSUR is .FALSE., the namelist value XZEFIM sets the
    central resistivity Zeff value.

for a constant resistivity Zeff (available if NLVSUR=.FALSE.)
just set NLZFIM=.TRUE. and XZEFIM=<desired value>.

-----------

if NLVSUR is .FALSE. but there is surface voltage data, the measured
and predicted surface voltage are both passed to the plotting code for
comparison (they need not agree).

see information on magnetics

5 Zeff_and_predictive_runs

When Te is predicted, there are (for stability reasons) restrictions
on Zeff reconstruction options:

  (a) Zeff cannot be set from a resistivity analysis;
  (b) Visible Bremsstrahlung (VB) data analysis cannot be used.

The basic reason is that these methods are sensitive to Te and so if
the predicted Te deviates from the experimental value, plasma 
composition is affected, and can be affected radically in the edge 
regions, leading to unexpected results and crashes.

TRANSP "datchk" has been modified to reject namelist settings 
requesting such Zeff treatment when Te prediction is present.

So, the advice is to extract the unconstrained Zeff(x,t) from the
output of a TRANSP analysis run-- this is the ZEFFI profile data.

This can be saved as a 2d Ufile vs. (x,t) with naming of your choice.
Then:

  (a) turn off any prohibited switch settings (NLZEFM, NLZVBR, NLZVB2);
  (b) disable time dependent Zeff model switching (remove NZEFMOD and 
      TZEFMOD) from the namelist;
  (c) specify your Ufile as input: PREZF2, EXTZF2, NRIZF2=5, no NSYZF2.

VB data can still be input to the run and passed through to output for
comparison, but, it cannot be used directly for setting of Zeff while
Te prediction is in effect.

4 POWER_RADIATED
in the TRDAT namelist set
PREBOL,EXTBOL to point to the bolometer/power radiated UFILE.  If the
UFILE is 1d it is assumed to contain "wide angle" data in watts, vs.
time.  A flat radial radiation profile will be assumed.  If 2d data
is found, set NRIBOL, NSYBOL to specify the data plasma coverage and
symmetrization option in the usual way (cf DATA_SYMMETRIZATION).

in the TRANSP namelist, a fudge is available:

set PRFAC = fraction of THERMAL neutral eflux power to subtract out
of the power radiated profile before using the profile in the 
electron energy balance.

note that neutral beam eflux cannot be subtracted.  In anycase it
is not isotropic.  Beam eflux can overwhelm strategically placed
bolometers.  Beam neutral eflux effects on bolometers can be
simulated in TRANSP - see notes on the EFLUX_SIMULATION.  The 
simulation is usually subject to significant uncertainties due to
non-axisymmetry of the neutral population (re. toroidal locations 
of neutral beams, gas valves, limiters, etc.) which cannot be 
taken into account in TRANSP.
...new Aug 1986...
set NRIBOL to specify spatial coordinate definition-- see section
on DATA_SYMMETRIZATION.  Bolometer files may be defined vs. 
major radius, etc., now.

5 Calculated Power Radiated
The power radiated due to bremsstrahlung, impurity line radiation and
cyclotron radiation can be calculated.  The calculated radiated power
can then be used in place of bolometer data for the radiated power
used in transp.  This is controlled through the NPRAD namelist variable,
  NPRAD = -1 -> no radiation loss and suppress theory calculation
        =  0 -> use PREBOL,EXTBOL as corrected by PRFAC for the
                radiated power -- suppress theory calculation (old default)
        =  1 -> Te input data => use PREBOL,EXTBOL for radiated power
                Te predicted  => use calculated theory data for
                                 radiated power
                theoretical calculation is performed (new default)
        =  2 -> always use theoretical calculation for power radiated.

Additional namelist variables control the terms and output generated
through the radiated power calculation,
  NLRAD_BR = .True. -> calculate bremsstrahlung by impurity species,
                       total bremsstrahlung is always calculated
  NLRAD_LI = .True. -> calculate impurity line radiation
  NLRAD_CY = .True. -> calculate cyclotron radiation

  VREF_CY = Wall reflectivity used in cyclotron radiation formula
            (default 0.9 -- see radcal.f90)

Relevant RPLOT multigraphs,
  PBOLO  -> Radiated power as used along with breakdown between
            bremsstrahlung, line radiation and cyclotron radiation.
  CPBOLO -> Comparison of bolometer input data as adjusted for neutral 
            sources and the theoretical calculation
  PBOLOS -> Calculated radiated power by impurity species
  PBS_<Id> -> Calculated line and bremsstrahlung radiation for the species
              with periodic symbol Id (e.g. PBS_AR for argon)
  PBSLI_<Id> -> Calculated line radiation for all charge states for the species
                with periodic symbol Id (e.g. PBSLI_AR for argon)
  PBSBR_<Id> -> Similarly the calculated bremsstrahlung radiation
  PBX_<Id>_<C> -> Calculated line and bremsstrahlung radiation for the species
                  with periodic symbol Id and charge state C (e.g. PBS_AR_14)

4 PTCL_BALANCE(&neutrals)
Recent updates:
  April 2004:  NRCYOPT=2 option: suppress neutral recycling, ion 
               recycling proportional to RFRAC(...) except where
               single species recycling data is provided.
  February 1995:  Lithium now supported as a non-impurity thermal
                ion specie.  Ptcl balance options added.  Rewrite
                of this section of TRANSPHELP.
  August 1993:  max no. of non-impurity thermal species increased
                from 2 to 5 (Dec 2002: maximum is now 7 species).
  April 1992:  NDEFINE options added

choose subtopic

5 General_Remarks
Physics would indicate a strong dependence of particle balance and 
fluxes on conditions in the edge region and at the boundary.  Since 
TRANSP does not include a detailed edge model, a simplified description
of edge behavior must be used.

TRANSP offers a fair number of options in specifying this description.
Some of the guiding principles are:

  --> use input data for "gas flow" source.
  --> use ion confinement time or input data for "recycling" source.
  --> simple mechanisms (e.g. RFRAC(...) namelist control) specify the
      composition of the recycling source.
  --> (except for NRCYOPT=2): charge-exchange neutrals "bounce off" the
      wall and 100% are returned into the plasma, or,
  --> (NRCYOPT=2): charge-exchange neutrals are 100% lost; NRCYOPT=2
      augments the recycling source to compensate, in order to reach
      the user specified ion confinement time.
5 Global_Ptcl_Balance

For each thermal ion specie the global particle balance
(integrated over the plasma column) may be thought of as:

   dNi/dt = Sbi + G0i + R0i   - Fi          (A)

where

   dNi/dt = time rate of change of specie i population, ions/sec
    Sbi   = total beam fueling source (or sink by beam cx loss)
    G0i   = edge source -- gasflow neutrals
    R0i   = recycling source -- recycling neutrals
     Fi   = ion outflux

Typically, Sbi is set in advance by the beam model; G0i is
selected by specification of gas flow input data; R0i is set
by various recycling model options and/or use of input data,
and the various NDEFINE and NMODEL options determine Fi and
dNi/dt, while satisfying the profile constraints of the Zeff
and Quasineutrality equations

       ne = sum[all ion species] Zi*ni
  ne*Zeff = sum[all ion species] Zi**2*ni

and using the given data, ne, Zeff, and modeled fast ion
specie densities and their time derivatives.

Since equation (A) holds for each ion species individually, it also
holds for a Z-weighted sum of ion species; the summed form of the 
equation is used in some modeling options.

5 NDEFINE
New DMC April 1992

For plasma species ig = 1 to NGMAX, namelist control NDEFINE(ig)
determines how the density profile for species ig is to be 
determined:

NDEFINE(ig) = 0  (default)  use old TRANSP NMODEL system to 
  evolve the mix amongst NDEFINE(ig)=0 ions considered as a
  group.  At least one NDEFINE(ig)=0 specie must be given.

NDEFINE(ig) = 1  use single species predictive model driven by
  input radial transport data and fully specified sources.

NDEFINE(ig) = 2  the density profile itself is input data;
  data on recycling or Tau(p) still expected.

Details of models in subtopics.

6 Zero_NDEFINE
NDEFINE(ig)=0
=============

Species under this designation are controlled under the old TRANSP
NMODEL system, described by nearby subtopics.  There are changes 
in that new ways of specifying gas flow and recycling sources are
now available.

At least one NDEFINE(ig)=0 gas must be specified;  if only one
is specified, its density is determined by subtracting from the
electron density Z*known ion density for all the other ion
species.

Important controls for NDEFINE(ig)=0 gas species:

  NMODEL    -- mixing model
  FRAC(ig)  -- initial relative concentration
  RFRAC(ig), NLRCYC, NLTAUP, etc ... -- recycling controls
  GFRAC(ig), etc ... -- gasflow controls
  NRCYOPT   -- alternate recycling model control

6 One_NDEFINE
NDEFINE(ig)=1
=============

Predictive Transport for species ig.  The user must provide the
input profile Ufiles defining the transport (diffusivities and
flow velocities) as spelled out below.

Then, for species ig, the radial flow is given by one of the
following formulae:

    gamma = Vc * ( - Lf *grad(n) + n )    [1]

      or

    gamma = -D *gradn(n)  + Vc *n         [2]

where
    n is the species ig density, grad(n) the density gradient
           (predicted), and

    Vc is the non diffusive radial velocity (Ufile input).
    Lf is the diffusive flow scale length (Ufile input).
    D is the specie diffusivity (Ufile input).

At least one and at most two of these Ufile inputs are needed.
The following combinations are allowed:

    Vc only -- use formula [2], assuming D=0.0.
    D only -- use formula [2], assuming Vc=0.0.
    D and Vc -- use formula [2].
    Lf and Vc -- use formula [1].

Note: D is constrained to be between the namelist inputs DFIMIN and 
DFIMAX (cm**2/sec).  Negative diffusivities are not allowed.

Then, prediction is done using the continuity equation

    dn/dt = S - div(gamma)

Where the sources S are from beam fueling, gasflow and recycling
(more information below).

The transport profile inputs (profile Ufiles vs. time, space) 
have all the usual associated spatial range / symmetrization 
controls.  The basic Ufile name controls for the TRDAT namelist 
are:

For hydrogen:
  PREVCH,EXTVCH  and  PRELFH,EXTLFH  for Vc and Lf.
  PREDFH,EXTDFH  for D
For deuterium:
  PREVCD,EXTVCD  and  PRELFD,EXTLFD  for Vc and Lf.
  PREDFD,EXTDFD  for D
For tritium:
  PREVCT,EXTVCT  and  PRELFT,EXTLFT  for Vc and Lf.
  PREDFT,EXTDFT  for D
For helium-3:
  PREVC3,EXTVC3  and  PRELF3,EXTLF3  for Vc and Lf.
  PREDF3,EXTDF3  for D
For helium-4:
  PREVC4,EXTVC4  and  PRELF4,EXTLF4  for Vc and Lf.
  PREDF4,EXTDF4  for D
For lithium-6:
  PREVC6,EXTVC6  and  PRELF6,EXTLF6  for Vc and Lf.
  PREDF6,EXTDF6  for D

The source term S in the specie continuity equation is the 
sum of a net beam fueling source and the ionization source
from the thermal neutral transport model.

Thermal neutral transport (excluding beam halo effects) are
modeled in TRANSP using two edge sources:  a gas flow source
and a recycling source.  See the subtopic on gasflow and
recycling sources.

Special considerations:

Uniquely for the NDEFINE(ig)=1 model, ion outflux is pre-
determined by the value of the input transport profile data
at the plasma boundary (r=a).  If no recycling input source
data is provided, then the fraction of this ion outflux that
is recycled is controlled by the namelist input RECYCH(ig).
I.e. if RECYCH(ig)=0.0, none of this ion outflux is recycled
and the total ion density should fall rapidly; if RECYCH(ig)
is 1.0, then all of the ion outflux is recycled and the
ion density can never decline.  THE USER MUST SPECIFY A
REASONABLE VALUE for RECYCH(ig) -- species ig is being 
predicted without regard for other constraints; if the
prediction goes awry, leaving n(ig) > electron density,
then it will crash the TRANSP run.

Alternatively, the user may specify a total recycling 
source as an input Ufile.  However, this can result in
large dn/dt terms that may be hard to predict.  These
dn/dt terms might be thought of by defining a 
recycling "coefficient" expressed as

   (ion source due to recycling neutral ionization)
   ------------------------------------------------
                (total ion outflux)

If the total ion outflux is specified by the transport
model AND the recycling source by input data, then the 
recycling coefficient is determined and may not 
satisfy expected constraints (e.g. it might be larger
than unity, leading to dn/dt .gt. 0 due to recycling
alone).

To use NDEFINE(ig)=1, an initial condition must be given;
use FRAC(ig) to specify the relative concentration of the
specie at the start of the run.  This can be zero; the
specie can be introduced later by pellet, gas puff, 
recycling fraction, or beam injection.

By default, the specie density profile BOUNDARY CONDITION is
that the scale length match the scale length of the electron
density profile.  This has its hazards-- it assumes that the
electron density has a reasonable non-zero outward sloping 
gradient at the boundary.

Alternatively, the user may set (for ndefine(ig)=1 specie)

  fbdy_nd2(ig) = <fraction-of-electron-density>

where the number given is the fraction of the electron density
desired for specie ig, at the plasma boundary.  The fraction
should be well less than one.

An alternate recycling source model is available.  When using 
NRCYOPT=2, if separate recycling source data is not provided, 
the recycling source for the NDEFINE(ig)=1 species is simply

  RFRAC(ig)*[total ion recycling source].

and RECYCH(ig) is not used.

6 Two_NDEFINE
NDEFINE(ig)=2
=============

Modification, DMC, Feb. 2011: density input Ufile can now be
omitted; in this case density of species (ig) is set to:

   FRAC_NDEFINE2(ig)*[electron density]

using the new namelist array NFRAC_NDEFINE2; the default value
of the array elements is 1.0d-4 -- yielding just a trace amount
of the indicated ion specie.

----------
(description from before Feb. 2011):

In this model, the specie ion density profile is input 
directly from Ufile into the TRANSP code.  The input
Ufile names are:

For Hydrogen:
  PRENIH,EXTNIH
For Deuterium:
  PRENID,EXTNID
For Tritium:
  PRENIT,EXTNIT
For Helium-3:
  PRENI3,EXTNI3
For Helium-4:
  PRENI4,EXTNI4
For Lithium-6:
  PRENI6,EXTNI6

It is the responsibility of the user to assure that input
profiles are consistent with other data (electron density,
Zeff) at all times through the analysis.

Even with NDEFINE(ig)=2, gasflow and recycling sources
should be defined to complete the particle balance for
the specie.  See the subtopics on gasflow and recycling.

5 Initial_Condition
Since the species mix is advanced in TRANSP by numerical
solution of PDEs, an initial condition must be specified.
The initial condition gives the relative concentration of
species at time t=TINIT, at the start of the run.

  NG gives the number of species with non-zero density at
     the start of the run.  Then, for species IG, IG=1 to NG,

  FRAC(ig) specifies the relative concentration for species ig.
     Note that FRAC applies only to species for which NDEFINE(ig)
     is 0 or 1; for NDEFINE(ig)=2 the initial profile is taken
     from the input data.
       All initialized specie density profiles have the same
     relative shape, proportional to the shape of the profile

       Nshape = 
       electron density - sum[Zi * known specie i ion densities]

     the main correction from electron density usually being
     impurity ions, controlled by the initial value of the
     Zeff profile.
       Using this shape, a set of multipliers f(ig) are found
     for NDEFINE(ig) = 0 or 1 ions, such that

       f(ig) = FRAC(ig)/ [sum over relevant ig of FRAC(ig)]

     and the density n(ig) = f(ig) * Ntotal.  Ntotal has the
     same shape as Nshape but will have a slightly different
     magnitude if species ig are a mix of Hydrogen, Helium
     and Lithium.  This is because the non-Hydrogenic species
     have Z>1 and the quasineutrality requirement must be
     satisfied:

       electron density 
        = sum[over all ion species jg of Z(jg)*n(jg)].

     The initial condition (and all TRANSP density solutions)
     will satisfy the quasineutrality condition and the Zeff
     equation

       electron density * Zeff 
        = sum[over all ion species jg of Z(jg)**2*n(jg)]
5 Introducing_New_Species
The TRANSP namelist control NGMAX specifies the maximum number
of plasma gasses that will ever be present during the TRANSP 
run.  The initial number of gasses NG can be less than NGMAX.
The maximum allowed value of NGMAX is now 5 (TBT Aug 1993).

Any gas that is "present" in a run has a minimum density of
RHMINM*[the electron density]; RHMINM defaults to 1.0E-12.

NDEFINE(ig)=2 gasses must be present throughout the run.

New gasses may be introduced in the following ways:
  (1) pellet injection of the new gas,
  (2) neutral beam injection of the new gas,
  (3) non-zero gasflow or recycling source of the new gas.
When TRANSP detects any of these conditions it increases the
number of gasses NG known internally to the code and gives
the new gas an initial density of RHMINM*[the electron density],
taxing other species as necessary to maintain quasi-neutrality.

Pellet injection gives the new gas a "macroscopic" density
immediately; other sources cause the new gas density to 
increase gradually from its very low RHMINM determined 
initial value.

A note on indexing -- if specie jg is "present" then TRANSP
internal requirements force species 1,2,...,(jg-1) to be
present as well.  Therefore, if the desire is to start
the run with NG < NGMAX and add species later, then, the
added species should be indexed in order of their arrival.

5 NMODEL
The NMODEL control applies ONLY to thermal ion species ig for which
NDEFINE(ig)=0.

Choice of NMODEL affects ONLY the mixing of NDEFINE(ig)=0 isotopes 
in a TRANSP run.  If there is only one isotope (e.g. a pure D+ 
plasma), then the choice of NMODEL has no effect.

The TRANSP namelist control NMODEL is used to choose among various
particle balance options:

  NMODEL=1:  "species independent density profile shape model".  
Simultaneous solution of Zeff and quasi-neutrality equations yields
a thermal ion density profile.  With NMODEL=1 the individual
specie density profiles are assumed to have a shape proportional to
this total profile.  What fraction is assigned to which species is
a function of time determined by global particle balance.  Gasflow,
recycling, and neutral beam fueling determine the evolution of the
specie fractions.

  NMODEL=2:  "species independent radial velocity model".  
As with NMODEL=1 the total (i.e. Z weighted summed) ion density 
profile is calculated.  But now the Z weighted summed PARTICLE 
BALANCE (CONTINUITY) equation is solved:

   d/dt[sum Zi*ni] = [sum Zi*Si] - [sum Zi*div(fluxi)].

Using summed beam and recycling sources [sum Zi*Si], and dne/dt and 
dZeff/dt and fast ion density data to get d/dt[sum Zi*ni], this
equation is solved for the summed flux.  The resulting flux
profile implies an "average" radial ion velocity profile.  In
NMODEL=2, this radial velocity profile is assumed to apply
individually to all species; i.e. the assumption is that all
species move radially with the same velocity.  Then the 
continuity equation is solved individually for each specie,
to advance the mix.
  Note (dmc Sept 2004): NMODEL=2 is now the same as NMODEL=4
but with a small, constant diffusivity, set equal to DFIMIN.
DFIMIN=0 is the default.

  NMODEL=3:  ** no longer available **
as with NMODEL=2, the Z weighted summed continuity
equation is solved to extract an assumed constant D in this
"species independent diffusivity model".  However, This model
is not stable against grad(n)=0, D=infinity type singularities
and is thereful not reliable and not recommended for use.

  NMODEL=4:  "mixed model".  As with NMODEL=2, the Z weighted 
summed continuity equation is solved to yield a Z weighted summed
flux constraint.  But in this model each ion species evolves 
independently, using species radial flux modeled as the sum of 
two terms:

    flux = D * grad(n)   +  V * n

Where D will essentially be input while the "non-diffusive" V will be
computed to satisfy the global flux constraint.

When using NMODEL=4, select the input diffusivity D0 with:

    NDIFFI=1 to set a time and space independent input diffusivity in
             the namelist:
               DIFFUS = the input diffusivity (cm**2/sec)
    NDIFFI=2 to input a diffusivity Ufile.  this Ufile is input
             through the "electron" diffusivity channel of TRDAT;
             set the name via namelist controls PREDE2, EXTDE2;
             the Ufile units should be cm**2/sec
    NDIFFI=3 to use the "net" electron diffusivity fluxe/grad(ne)
             from the electron particle balance previous timestep,
             as the input diffusivity for the ions.
    NDIFFI=4 to use the electron diffusivity (as in NDIFFI=3) with
             a correction for the neoclassical Ware pinch.
    NDIFFI=5 to use the formula D0 = chi(i), chi(i) from the ion
             power balance calculation
    NDIFFI=6 to use the formula D0 = chi(e), chi(e) from the
             electron power balance calculation

    The local time rate of change of D0 is limited by namelist
    control DLTKIE; this constrains the factor by which D0 can
    change, per millisecond of model time.  DLTKIE is also used
    to constrain the rate of change of chi(i) and chi(e) when
    these are being used predictively.

    D0 is applied to individual species as follows.

Set

    DFIMIN = the minimum allowed diffusivity
    DFIMAX = the maximum allowed diffusivity

    DIFAC(...) = species dependent diffusivity anomaly factor

To obtain the diffusivity (for ion species IG):

    D = min( DFIMAX, max( DFIMIN, DIFAC(IG) * D0 ))

where D0 is the input diffusivity (e.g. DIFFUS for NDIFFI=1).

Use the DIFAC control to make one species diffuse more rapidly than
another, if an isotope dependent effect is desired.

Solution of the particle balance using available data puts a
constraint on the radial flux; this is in general not met by a
diffusion model alone.  Therefore a non-diffusive velocity must
be computed for each species, so that the sum of species fluxes
satisfies a global constraint.  However, this still leaves NG-1
degrees of freedom (where NG=# of species); one may make one
species more "mobile" than another, to carry a larger fraction
of the flux needed to meet the global constraint.  Set

    VIFAC(ig) = non-diffusive flow velocity factor for species ig.

    (caution:  VIFAC(ig) .gt. 0.0 required, and 
      VIFAC(IG1)/VIFAC(IG2) .ge. 0.1 required for all IG1,IG2)

Only the ratios VIFAC(ig)/VIFAC(1) are important; i.e. the
specifications

    VIFAC=1.0,2.0
and
    VIFAC=0.5,1.0

are entirely equivalent.

Example:  to make species 1 "three times as mobile" as species 2 in
the non-diffusive flow term, set VIFAC=3.0,1.0.

Another Example:  if the input diffusivity is set to 0.0 and 
VIFAC=1.0,1.0 is specified, then NMODEL=4 does the same thing as
NMODEL=2.

Defaults:  NDIFFI=1, DIFFUS=0.0, DFIMIN=0.0, DFIMAX=1.e5,
    DIFAC(ig)=VIFAC(ig)=1.0 for all ig.  These controls have effect
    only when NMODEL=4 is in use.

5 Upwind_Differencing
(New DMC Dec 2003)

For both NDEFINE(ig)=1 species and for mixing model species with
under NMODEL=2 or NMODEL=4, which involve a mix of diffusive
and advective radial particle transport, situations can arise
where an "upwind differencing" adjustment is needed to prevent
radial oscillations in regions where the advective transport
exceeds the diffusive transport by a sufficiently large amount.

Such radial oscillations are independent of timestep size; they
represent a "mathematically correct" but physically dubious
solution of the equations.  Sensitivity is to these oscillations
is heightened when increased radial resolution is employed.

(Since TRANSP used to be run almost exclusively with only 20
radial zone resolution, these radial oscillations were seldom
seen in the early years of use of the code).

These oscillations are a well known phenomenon of computational
fluid dynamics, for which there is an effective cure: upwind
differencing of the advective term:

Instead of using the center difference formula for the flux

  gamma = -D*grad(n) + n*v
        = -D*<1/dr>*(n[j-1]-n[j]) + (n[j-1]+n[j])/2 * v

for an outward flow v > 0 use instead

  gamma = -D*<1/dr>*(n[j-1]-n[j]) + (n[j-1]) * v

taking the density from the "upwind" zone, instead of the
average value between the upwind and downwind zones.

This yields an approximate solution of the continuity equation
which is less accurate (1st order instead of 2nd order in spatial
stepsize), but more stable.

In TRANSP an effort will be made to preserve accuracy, and only
use upwind differencing where needed.

It has been found empirically that the quantity

  u = UPWIND0*<1/dr>*D/abs(v)

  UPWIND0 = (namelist control, default value = 0.02, roughly
     related to "maximum allowed" radial oscillation size
     delta(n)/n -- conservatively).

  <1/dr> = flux surface averaged inverse width of zone (cm**-1)
    D    = diffusivity, cm**2/sec
    v    = velocity, cm/sec

can be used effectively to "turn on" upwind differencing only
when needed.  Generally,

  u >= 1 means the system is stable
  u < 1 means the radial oscillations are likely to occur;
  u << 1 means the radial oscillations are likely to be strong.

TRANSP uses the parameter

  w = min(1,u)

to control the use of upwind differencing: w=0 means to use pure
upwind differencing; w=1 means to use center differencing of the
advective term; w=0 means to use pure upwind differencing; 
intermediate values of w mean, use a mixture of the two.

At present, upwind differencing is implemented only in the 
ion specie (mixing) continuity equations.  At some point it
may also be needed in predictive temperature or toroidal
angular momentum equations (this will be implemented if/when
the need arises).

The multigraph UPWIND has been added to show the upwind
adjustment:  there is one profile for each species.  The 
profile values are to be interpreted as follows:

  0 -- no adjustment, advective term is center differenced.
  +1 -- full upwind adjustment for v > 0
  -1 -- full upwind adjustment for v < 0

intermediate values reflect intermediate amounts of adjustment.

6 Upwind_profile_outputs

The UPWIND multigraph contains upwind differencing parameter 
profiles.  These will be identically zero for prescribed plasma
quantities.  For predicted quantities these values are provided
as a function of radial flux coordinate at outer cell boundaries:

  0 -- no adjustment, advective term is center differenced.
  +1 -- full upwind adjustment for v > 0
  -1 -- full upwind adjustment for v < 0

The individual output profiles are:

  UPWIND_H, UPWIND_D, UPWIND_T, ... -- main plasma species

  UPWIND_TE ... for electron energy balance (TE prediction)
  UPWIND_TI ... for ion energy balance (TI prediction)
  UPWIND_MO ... for angular momentum balance (omega_phi prediction)

5 Gasflow_Source
Gasflow neutral sources can be specified by Ufile input (if
none are specified, the gasflow is taken to be ZERO).

Except when NRCYOPT=2, gasflow neutral sources actually specify 
neutrals ionized in the plasma -- i.e. if gasflow input data says 
1.0e20 atoms/sec, then an integrated ion source of 1.0e20 ions/sec 
will be supplied.  This is enforced by having the neutral transport
model treat neutrals escaping the plasma as 100% reflected back into
the plasma.

If NRCYOPT=2, charge exchange neutrals exiting the plasma are instead
assumed to be 100% lost, and, the net ion source will be accordingly
reduced compared to the neutral source.  If a global particle 
confinement time was specified, extra recycling source will be
provided to meet this.

If NLRCYC=.T, gasflow Ufile data summed over species may be
provided.  The summed data applies only to isotopes with Z
number matching namelist specification XZRCYC.  Among these
species, the gasflow is distributed using the namelist array
GFRAC, i.e.

   g(ig)=GFRAC(ig)/[sum over relevant jg GFRAC(jg)]
   gasflow(ig)=g(ig)*[input data]

If NLRCYC=.F or for species not having Z=XZRCYC, gasfflow data
can only be provided as species specific Ufile data.  Z for
species ig is BACKZ(ig).

For mainly historical reasons, GFRAC may be made a function
of time.  If NLRCYC=.T and appropriate summed gasflow Ufile
data is provided, this time dependent GFRAC could theoretically
be used to specify a gasflow first of one species, then
another.  See the subtopic.
6 GFRAC_vs_T
Individual specie gas flows vs. time may be specified by Ufile.
However, if such data is not available, then the time dependent
gas flow fractions may be entered in the namelist as follows.

GFRAC, TFGRAC and GFRACA only have an effect IF NLRCYC=.T and 
positive summed gasflow Ufile data is in use.

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

The gasflow fractions GFRAC may be specified time-dependently
via the namelist controls TGFRAC and GFRACA.

GFRAC(ig) give the initial gasflow fractions

TGFRAC(it) give the gasflow fraction transition times IN ASCENDING
ORDER.  The index it ranges from 1 to 8.  The default is
TGFRAC(it) = +infinity for all indices "it".

GFRACA(ig,it) give the new gasflow fractions which go into effect 
at time TGFRAC(it).

NOTE:  You can INTRODUCE a NEW PLASMA SPECIES using these controls.

Example:

  BACKZ=1.0,1.0   ! D, T
  APLASM=2.0,3.0
  NG=1            ! INITIALLY, ALL D
  GFRAC=1.0,0.0
  TINIT=2.5       ! START ANALYSIS AT 2.5 SECONDS
  TGFRAC(1)=2.65         ! TURN ON T GASFLOW AT 2.65 SECONDS
  GFRACA(1,1)=0.0,1.0
  TGFRAC(2)=2.70         ! REVERT TO D GASFLOW AT 2.70 SECONDS
  GFRACA(1,2)=1.0,0.0
5 Recycling_Source
TRANSP offers many ways of specifying the recycling sources.
These are the union of options requested by users and
implemented over 15 years of code use.

The main flavours of options are:

  o  specify Tau(p) -- the ion particle confinement time.
     the magnitude of the recycling source is set such that
     the balancing ion outflux reaches the level required
     to match the specified Tau(p) = N/[outflux rate].

     -> NLTAUP=.T for Tau(p) vs. time input Ufile
     -> See NRCYOPT=1 for new option, a mixed ion 
        reflection / limiter outgas model, based on
        suggestions by Tim Jones at JET, added 1/1995.
     -> See NRCYOPT=2 for a 2nd new option, with a 
        modified treatment of escaping charge exchange 
        neutral atoms.

  o  specify recycling source magnitudes directly

     -> Ufiles for individual species recycling sources
     -> NLRCYC=.T and Ufile for summed recycling source
     -> Tau(p) is now an output of the calculation.

6 RFRAC
RFRAC(ig) specifies the species distribution of the recycling
source.  RFRAC defaults "off", which means the recycling fraction
tries to be inferred from quantities related to the edge density
fractions at the previous timestep.

  ==> it is recommended that RFRAC be specified.
      If RFRAC is defaulted, various extra restrictions apply
        in specifying recycling source data.
      There have been instances of unexpected / unstable
        evolution of plasma composition, with RFRAC defaulted.

  ==> RFRAC can be safely omitted if recycling source data
      is supplied individually for each ion species.

Generally, if RFRAC is specifed, then, defining

  r(ig)=RFRAC(ig)/[appropriate sum over jg of RFRAC(jg)]

the recycling source for species ig is

  r(ig)*[the total recycling source]

where the total recycling source is as specified by input data
(e.g. NLRCYC=.T summed recycling source data) or is as required
to match a global Tau(p) specification.

The set of species summed over depends on the context:

   NLRCYC=.T: summed source applies to species ig for which
     BACKZ(ig)=XZRCYC.

   Tau(p):  the NDEFINE(ig)=0 ions considered as a group.

RFRAC can also be used to scale the recycling rate for species
for which no data is provided.  For example, if a plasma
contains H,D,T and Lithium, and the H,D,T summed recycling
is controlled by NLRCYC=.T data, then the Lithium recycling
is scaled using the formula

                    RFRAC(Li)*[H+D+T recycling data]
   [Li recycling] = --------------------------------
                       RFRAC(H)+RFRAC(D)+RFRAC(T)
7 RFRAC_vs_T
Individual specie recycling vs. time may be specifiec by Ufile.
However, if such data is not available, then the time dependent
recycling fractions may be entered in the namelist as follows.

The recycling fractions RFRAC may be specified time-dependently
via the namelist controls TRFRAC and RFRACA.

RFRAC(ig) give the initial recycling fractions

TRFRAC(it) give the recycling fraction transition times IN 
ASCENDING ORDER.  The index it ranges from 1 to 8.  The default
is TRFRAC(it) = +infinity for all indices "it".

RFRACA(ig,it) give the new recycling fractions which go into 
effect at time TRFRAC(it).

NOTE:  You can INTRODUCE a NEW PLASMA SPECIES using these
controls.  The following is a crude example:

  RFRAC=1.0,0.0,0.0   ! all recycling is species 1 initially
  TRFRAC=2.0,3.0      ! transition times
  RFRACA(1,1)=0.5,0.5   ! after 2.0 seconds, ratio is 50:50
  RFRACA(1,2)=0.33,0.33,0.33  ! after 3.0 secs, ratio is 33:33:33

6 RECYCH
For some recycling models, RECYCH(ig) specifies the "prompt 
recycling coefficient" for species ig ion outflux.

In particular:

RECYCH is specified for all species when the NRCYOPT=1 model
is used;

For a species ig modeled using predictive transport
(NDEFINE(ig)=1) and for which no other recycling source 
data is provided, the recycling source for this species
is RECYCH(ig)*[ion outflux].  The ion outflux is
determined by the transport model for the species.

6 Sources
Recycling source information may be provided as Ufile input,
specifying total recycling ion source as a function of time.

Use NLRCYC=.T to specify a summed source applying to all
species jg satisfying BACKZ(jg)=XZRCYC.  XZRCYC=1 by default.

If NLRCYC=.F or BACKZ(jg).ne.XZRCYC, recycling source may
be specified on a species by species basis.

Recycling sources override Tau(p) data.  If source data is
provided for *any* specie, Tau(p) is overridden for *all*
species.  If source data is missing for some species, RFRAC
is used to scale the missing source information from the
information provided.

For a species ig with NDEFINE(ig)=2, one may use the switch
    NLRCYI=.T 
to have TRANSP give this (density profile input) species
the recycling source rate needed to obtain the same global
particle confinement time as the NDEFINE(jg)=0 ion species.

For impurities, set
    NLRCYX=.T 
to enforce impurities having the same global particle
confinement time as thermal ions.

A nearby topic specifies namelist controls for Ufile names.
6 Tau_p
Particle confinement controls are relevant when using NRCYOPT=1
or when no other recycling source data is provided.  When
source data is provided, Tau(p) controls are overridden.

The thermal ion ptcl confinement parameter Tau(p) is INPUT:
  it may be input as a time-dependent UFILE via TRDAT by setting
    NLTAUP=.TRUE. (TRANSP namelist)
  and specifying
    PRETPI,EXTTPI to name the UFILE (TRDAT namelist).

Alternatively, to specify time-independent Tau(p), set
    TAUPH(ig), ig=1 to NGMAX for individual species Tau(p)
    and TAUPO for impurity Tau(p).

Note that for various NDEFINE(ig)=0 species NMODEL options, the
mixing model may preclude matching the Tau(p) for all the
individual species; instead an "average" Tau(p) is matched.
The general practice when using Tau(p) has been to specify
the same Tau(p) for all species.  With NLTAUP=.T this is
enforced.

  Tau(p) fixes the thermal ion outflow accross the plasma boundary.
The relation is 
  outflow = (total number of ions in plasma) / Tau(p)
6 NRCYOPT_EQ_1
[New DMC 26 Jan 1995]

A new recycling model is now available.  The model is based on
suggestions by Tim Jones at JET.  The model is activated by
setting 

    NRCYOPT=1

in the namelist.  (Default is NRCYOPT=0).

The model has the following features:

   o  Input global Tau(p) by namelist or using NLTAUP=.T
      (Tau(p) data must be used; recycling sources cannot
      be specified).

   o  For each ion species ig the recycling neutral flux is 
      given by

      F0i = Fi(ig) * RECYCH(ig)  +  F0lim * RFRAC(ig)/Rnorm

      where the namelist input RECYCH(ig) specifies the
      fraction of species ig ion outflux Fi(ig) that is
      "promptly" recycled, and RFRAC(ig) specifies the
      fraction of some "limiter outgas" flux F0lim that
      is assigned to species ig.  F0lim is adjusted to
      match the input Tau(p).  Since a change in F0lim
      affects the Fi(ig) terms also, this is an iterative
      process, but it converges rapidly.  Rnorm denotes
      the sum over all species jg of RFRAC(jg).

RFRAC and RECYCH must be specified.  All RFRAC(ig) must
be non-negative; all RECYCH must be between zero and 0.95.

6 NRCYOPT_EQ_2
[New DMC 30 Apr 2004]

Another new recycling model is available.  In this model, recycling
of neutral atoms "as neutrals" is suppressed.  Unlike in the other
models, charge exchange neutrals exiting the plasma are not reflected
back in at low energy, and so, *all* particle recycling is controlled
by a particle confinement time specification, with RFRAC(ig) giving 
the species-by-species fractions of the recycling neutral flux.

For NDEFINE(ig)=1 and NDEFINE(ig)=2 species, separate recycling sources
may be specified.  If they are not specified, RFRAC(ig) applies to these
species as well as the NDEFINE(ig)=0 species.

The particle confinement time used is an edge-density-weighted average
of the namelist particle time TAUPH(ig) over all ion species.  Exception:
for NDEFINE(ig)=1 species the transport is specified, and particle 
confinement is taken from the species transport model instead of TAUPH.

Unlike the other modeling options, explicitly specified gas flow and
recycling neutral sources result in ion sources of reduced magnitude,
because, lost charge exchange neutrals are not reflected back into the
plasma.

To get this model, set

    NRCYOPT=2

in the namelist.

6 Rules_summary
NRCYOPT=2 means -- control total recycling with Tau(p), distribute
the recycling flux among species using RFRAC(...).

In NRCYOPT=2, exiting charge exchange neutrals are treated as 100%
lost. In all other models, exiting charge exchange neutrals are 100%
reflected back into the plasma at low energy.

NRCYOPT=1 means -- used mixed ion reflection / limiter outgas
  model.  Namelist Tau(p) may be specified; Tau(p) vs. time may
  be specified using NLTAUP=.T and providing a UFile (set
  PRETPI/EXTTPI in the TRDAT namelist).
  ==>required:  RFRAC and RECYCH must be specified.
  ==>disallowed:  recycling source Ufile input by species or
       by NLRCYC=.T.  NLRCYI=.T is not allowed either.

NRCYOPT=0 means -- use Tau(p) or recycling source data provided
  to determine recycling sources on a species by species basis.
  NDEFINE(ig)=0 species:
    NLRCYC=.T
      RFRAC defaulted
        ==>restriction:  all species with NDEFINE(ig)=0 must
           also have BACKZ(ig)=XZRCYC; no specie with
           NDEFINE(ig).ne.0 can have BACKZ(ig)=XZRCYC.
      RFRAC specified
           NDEFINE(ig) not restricted for BACKZ(ig)=XZRCYC set.
           Species without recycling source data can have their
             sources scaled from species with recycling source
             data using RFRAC.
    NLRCYC=.F
      RFRAC defaulted:
        no recycling source data ==> use Tau(p)
        complete recycling source data for all species OK
        restriction:  recycling source data for some species
          but not others **not allowed**.
      RFRAC specified:
        no recycling source data ==> use Tau(p)
        complete recycling source data for all species OK; RFRAC
          then not in use.
        recycling source data for some species but not others:
          use RFRAC to scale recycling source for the missing
          species.
  NDEFINE(ig)=1 species
    if source data is provided by species recycling source or
      from NLRCYC=.T data with RFRAC(ig), use it.
    if no data:  recycle RECYCH(ig)*[predicted ion outflux]
    Tau(p) is not used.
  NDEFINE(ig)=2 species
    use data if provided (individual specie source or NLRCYC=.T
      with RFRAC(ig) specified).
    if no data:  use Tau(p), or,
      if NLRCYI=.T, use the net Tau(p) of the NDEFINE(ig)=0
      species.

If any recycling source data is provided, Tau(p) input is
overridden and NLTAUP=.T cannot be used.

If RFRAC is defined, NLRCYC=.T recycling source data is
distributed using the RFRAC values given.  If source data
is provided for some species but not for others, RFRAC is
used to scale the recycling source magnitude for the
species for which data was not provided.

If RFRAC is defaulted, an "effective" RFRAC floats off the
predicted edge density fractions.  This mode of operation
is not recommended.

6 Constraints
There are some constraints built into the particle balance
model.  These are:

  TAUPMN -- (namelist specified minimum Tau(p), seconds).

     If Ufile input (Tau(p) or source data) would imply
     a confinement time less than TAUPMN, then the data
     is overridden and TAUPMN is imposed.

  Tau(p) is finite and positive

     Tau(p) = N/[ion flux]

     This means that the ion flux across the outermost flux
     surface is expected to be positive.  If dN/dt is large
     then it might be necessary to supply additional ion
     source to balance this dN/dt and still have an outward
     ion flux at the boundary.  TRANSP will do this.

     Exception:  for NDEFINE(ig)=1 species, the ion flux
     (including at the boundary) is controlled by the
     species transport model.

If data influencing the total ion density N are noisy (i.e.
noisy Zeff vs. time data) then these constraints can come
into play -- it will show up as noise in the recycling
source magnitudes, necessary in effect to keep the ion
outflux in bounds.

5 Ufiles_for_Gasflow_&_Recycling
DMC Apr 1992 -- 1d Ufile input options now exist for controlling
gasflow and recycling sources vs. time on a species by species
basis.  These may be used for all non-impurity thermal ion
species j with any value of NDEFINE(j), isotopes of Hydrogen,
Helium or Lithium.  

The old TRANSP option NLRCYC=.TRUE. can still be used for 
to specify gasflow and recycling data summed over species.
The NLRCYC=.T data gives the sums for species ig which satisfy
    Zi=BACKZ(ig)=XZRCYC
where XZRCYC is a namelist input that defaults to 1 for
isotopes of Hydrogen.

If NLRCYC is set .TRUE., the following Ufiles must be provided:
  PREGAS,EXTGAS -- total gas flow ion source summed over 
    Z=XZRCYC isotopes, vs. time.
  PRERCY,EXTRCY -- total recycling ion source summed over 
    Z=XZRCYC isotopes, vs. time.

For species NOT covered by NLRCYC=.TRUE. data:

To specify Hydrogen sources:
  PREGFH,EXTGFH -- Hydrogen gas flow ion source vs. time Ufile
  PRERCH,EXTRCH -- Hydrogen recycling ion source vs. time Ufile
To specify Deuterium sources:
  PREGFD,EXTGFD -- Deuterium gas flow ion source vs. time Ufile
  PRERCD,EXTRCD -- Deuterium recycling ion source vs. time Ufile
To specify Tritium sources:
  PREGFT,EXTGFT -- Tritium gas flow ion source vs. time Ufile
  PRERCT,EXTRCT -- Tritium recycling ion source vs. time Ufile
To specify Helium-3 sources:
  PREGF3,EXTGF3 -- Helium-3 gas flow ion source vs. time Ufile
  PRERC3,EXTRC3 -- Helium-3 recycling ion source vs. time Ufile
To specify Helium-4 sources:
  PREGF4,EXTGF4 -- Helium-4 gas flow ion source vs. time Ufile
  PRERC4,EXTRC4 -- Helium-4 recycling ion source vs. time Ufile
To specify Lithium-6 sources:
  PREGF6,EXTGF6 -- Lithium-6 gas flow ion source vs. time Ufile
  PRERC6,EXTRC6 -- Lithium-6 recycling ion source vs. time Ufile

The units of all input 1d ion source rate files are N/SEC or
"number of ions per second", vs. time.

If NLRCYC=.T data is used, the individual specie recycling
data can not be provided for any specie covered by the NLRCYC
data.  The TRDAT program enforces this and similar restrictions.

If any of the above Ufiles are used, the Tau(p) vs. time Ufile
specified with NLTAUP=.T, PRETPI/EXTTPI may NOT be used.
5 General_comments_Gasflow_&_Recycling
TRANSP uses a main plasma thermal neutral transport model
to distribute the total sources in a profile across the 
plasma column; these sources are then included in the
integration of continuity equations to determine the 
evolution of specie ion density profiles.

Unless NRCYOPT=2, Gasflow and Recycling sources in TRANSP are 
treated in a global sense as ion sources.  If a gasflow or 
recycling neutral source of 1.0e20 atoms/sec is specified, this 
will result in an ion source of 1.0e20 ions/sec distributed 
inside the plasma column.  This is done in the neutral transport
model by considering charge exchanged escaped neutrals as 100%
"bouncing off the wall" and returning to the main chamber.
This behaviour is a modeling choice -- so that the neutral
transport calculation determines the profile distribution
of sources but not their global magnitude.  This simplifies
control of plasma composition.  Since TRANSP lacks a 
detailed model of edge atomic/molecular physics and wall 
effects, this seems like an appropriate choice.  NRCYOPT=2
provides an alternative (see related topics).

Note that the gasflow ion source number is not necessarily 
simply related to gas flow (atoms/sec) at a valve far away 
from the plasma; probably an analysis of neutral transport 
through scrape-off region plasma (not included in TRANSP) 
will be needed to convert valve data to an estimate of main 
plasma total ion source rate.

Similarly, TRANSP does not have a facility for converting
H(alpha) or similar measurements to main plasma recycling
ion source rates; this analysis must be done outside TRANSP.
5 Neutrals
In TRANSP namelist set
  NSOMOD=1 to select FRANTIC analytic neutral transport model.
           (this is the only option currently available).

  NZONES_FRANTIC= number of radial zones in FRANTIC model
           (default is 20 zones).

Set RECYCB = recycling coefficient.  If R is the recycling source,
RECYCB*R "warm" neutrals are provided, and (1-RECYCB)*R "cold"
neutrals are provided.  RECYCB does not affect the magnitude of
the recycling source, only its energy distribution.

In the neutral transport models there are "types" of neutral sources
numbered as follows:
  sce  1 - "warm" recycling neutral source, ion species 1
  sce  2 - volume source (recombination + beam halo), ion species 1
  sce  3 - "cold" gaspuff neutral source, ion species 1
  sce  4 - "warm" recycling neutral source, ion species 2
  sce  5 - volume source (recombination + beam halo), ion species 2
  sce  6 - "cold" gaspuff neutral source, ion species 2
  sce  7 - "warm" recycling neutral source, ion species 3
  sce  8 - volume source (recombination + beam halo), ion species 3
  sce  9 - "cold" gaspuff neutral source, ion species 3
    --etc-- (up to 7 species)

The original TRANSP running instructions (20 years ago) were to
set E0IN(js)=energy of neutrals entering via source number js. This
never had any effect on volume sources which enter at the local Ti.
Note also the warm source temperatures E0IN(1), E0IN(4), ... are 
reset as described below. So, only E0IN(3), E0IN(6), ... etc., 
affect the results of the TRANSP model.

NOTE usually the wall source is dominated by recycling.  Thus if
RECYCB=1.0, the important energy parameters in terms of neutral
penetration are E0IN(1), E0IN(4) etc.

  MOD0ED=1, the default: if time dependent recycling temperature
    data is provided, use it. Otherwise, use TIEDGE namelist input to 
    set the recycling neutral temperatures E0IN(1), E0IN(4), etc.
    NOTE: if time dependent data is provided, MOD0ED=1 is enforced.

Other options for setting "warm" source energies:
  MOD0ED=2  --  use TI0FRC=fraction of central ion temperature for 
                edge recycling sources (this option not available
                for PTRANSP runs).
    or
  MOD0ED=3  --  use electron temperature data at the edge for the
                recycling sources energy
    or
  MOD0ED=4  --  use ion temperature data at the edge for the
                recycling sources energy

For MOD0ED=3,4: "temperature data at the edge" means just beyond
the plasma boundary-- typically the outermost value provided in 
the case of TRDAT input of temperature profiles.

For each unit neutral source input, there is some fraction of that
source that is not ionized but comes out of the plasma as lost
charge exchange neutrals.

Since generally the global particle balance is being specified
outside the neutral transport model, these escaping neutrals
are returned to the main plasma for ionization (this is actually
done after the fact by solving a linear system of equations to
normalize the neutral transport code output).  The escaping
neutrals can be returned "cold" or "hot".  Set
  FH0ESC = fraction of escaping neutrals to return as "warm" recycling
source neutrals (remainder are returned "cold").  

Exception: if NRCYOPT=2, escaping neutrals are treated as lost instead
of being returned to the main plasma.  The ion source associated with
user specified neutral sources (e.g. gas flow) is accordingly reduced.

set NLRECO=.TRUE. to turn on the recombination volume neutral source.

6 FRANTIC_model

Reference:
S. Tamor, J. Comput. Phys. 40 (1981) 104.

This model (ANTIC) has been extended to include multiple ion and neutral
species (including Helium), interaction with fast ions, recombination,
volume neutral sources from beam deposition, and to use updated cross-
sections; it has also been extended to compute the effect of neutral
transport on momentum balance.

Advantage:
  Very fast, qualitatively correct description of neutral gas
  transport and penetration of the core plasma.  Energy, momentum,
  and particles are strictly conserved within the FRANTIC geometry.
  When data is transferred to a generalized flux surface geometry,
  particle, momentum conservation, and plasma frame energy balance
  are conserved perfectly.

  Quantitative correctness of the model depends on the following...

Caveats:

  => Simplified geometry!

The geometry in this code a set of nested cylinders of varying minor
radius and shifted centers based on the major radius locations of 
centers of flux surfaces in the target plasma equilibrium geometry.
Linear momentum transport is done in this shifted cyclinders geometry 
and then converted to torques by factoring in the cylinder major radius 
positions at the end.

  => Strictly 1d model!

Edge neutral source enters the plasma from any direction with equal
probability; there is no possibility for poloidal variation of the 
source.  All results are of course also 1d, with a presumption that
neutral density, temperature, and angular velocity are functions of
flux surface only, which may not be very realistic.  The results
can be treated as flux surface averages, but FRANTIC itself cannot
provide any 2d information.

6 Edge_Angular_Velocity
The angular velocity of the edge neutral sources can be controlled.
With similar indexing to E0IN, OMEG0IN(1), OMEG0IN(4), ... control 
the angular velocity of the "warm" recycling neutral source for for 
gas species 1, 2, ...; OMEG0IN(3), OMEG0IN(6), ... control the angular
velocity of the "cold" gas flow neutral source for species 1, 2,...

The default values for the OMEG0IN namelist array elements are ZERO.

MOD0ED_OMEGA controls the model for recycling source angular velocity:

  MOD0ED_OMEGA = 1 (the default) means (a) if time dependent data
     is available, use it; otherwise (b) use the namelist values
     OMEG0IN(1), OMEG0IN(4), ... unmodified.

  MOD0ED_OMEGA = 2 means use OMEG0FRC * [the edge ion angular velocity]
     for the angular velocity of the neutral source.  Default value
     for OMEG0FRC is 1.

The edge ion angular velocity means the data just beyond the plasma
boundary.

The gas flow source angular velocity is either the specified 
namelist array elements OMEG0IN(3), OMEG0IN(6), ..., or, time
dependent data for this quantity can be provided.

6 Input_data_vs_time

The following TRDAT f(t) input channels can be used to control
parameters related to the edge sources:

  TRC -- recycling neutral source temperature (eV).
  ORC -- recycling neutral source angular velocity (rad/sec).

  TGF -- gas flow neutral source temperature (eV).
  OGF -- gas flow neutral source angular velocity (rad/sec).

E.g. in the TRANSP namelist set PRETRC,EXTTRC to identify the "Ufile"
or MDS+ signal containing the time dependent input data for TRC.

Note that the same temperature (or angular velocity) is applied
to all species.  At present there is no provision for having 
these parameters vary from specie to specie.

6 RPLOT_outputs
The multigraphs most frequently used to look at neutral transport are:

  DENS0 -- neutral densities
  T0    -- neutral temperatures
  OMEG0 -- avg angular velocity

and, summed over all neutral sources:
  N0BAL -- ptcl balance
  TQ0BA -- angular momentum balance
  E0BAL -- energy balane

5 TRANSP_outputs
TRANSP outputs data specifying particle balance for all plasma
species; these particle balances show the terms in the specie
continuity equations

    dn/dt = S - div(gamma)

with the S term divided into two parts:  ion sources attributable
to the beam, and ion sources attributable to edge neutral sources
(gas flow + recycling).

The TRANSP outputs are in RPLOT profile "multigraph packages" with
the following names:

  EPBAL -- electron particle balance
  IPBAL -- ion particle balance (summed over all thermal ions)
  IMBAL -- impurity ion particle balance
  GHBAL -- H+ ion particle balance (if the plasma contains H+)
  GDBAL -- D+ ion particle balance
  GTBAL -- T+ ion particle balance
  GHE3BAL -- He3++ ion particle balance
  GHE4BAL -- He4++ ion particle balance
  GLITHBAL -- Li+++ ion particle balance

(For more information on using RPLOT, obtain a copy of the manual
"Accessing TRANSP Output:  A User's Guide" from D. McCune).

Edge neutral sources are divided into two types:  recycling and
gasflow.  The evolution of the magnitude of these sources is
given in the following scalar multigraphs (vs. time only):

  SBDYH -- H+ total recycling and gasflow ion sources
  SBDYD -- D+ total recycling and gasflow ion sources
  SBDYT -- T+ total recycling and gasflow ion sources
  SBDY3 -- He3++ total recycling and gasflow ion sources
  SBDY4 -- He4++ total recycling and gasflow ion sources
  SBDYL -- Li+++ total recycling and gasflow ion sources

These sources are under user namelist and/or data control, as
described in neighboring subtopics.

Set NLDBG0 = .TRUE. for additional debug output from the neutral
gas model.  This will produce detailed information on each 
individual neutral source (gasflow, recycling, and volume sources
for each species-- neutral densities, "temperatures", particle
momentum and energy balances are independently provided for each
neutral source.
5 Some_old_comments
Particle balance controls effect convection and charge exchange loss
terms in the electron and ion power balances.  Losses are generally
inversely proportional to TAU(P), especially near the edge regions,
but this can be strongly modified in the center, e.g. due to the 
presence of neutral beam fueling, or significant dn/dt.

The energy of edge neutral sources (E0IN controls) sometimes has
a significant effect on how far in the neutral density and source
function profiles associated with the recycling/ gas puff neutral
sources will penetrate.  But this penetration is even more strongly
affected by input density and temperature data.

Particle balance controls effect the neutral density profiles, which
in turn can modify beam charge-exchange loss, thereby indirectly
affecting beam heating.  However, to the degree that beam charge-
exchange is self-induced (in the beam halo), controls modifying
the recycling/ gas puff neutral sources will have little effect.
4 Radial_Resolution
(updated Sep 2007)
TRANSP has traditionally run with 20 radial zones, but the code
may now run with any number of radial zones, subject to limitations
of memory and disk space.

The performance of the main body of TRANSP and the Monte Carlo
fast ion model is only modestly effected by going to higher
resolution.  

The TRANSP main body and Monte Carlo and Fokker Planck codes
have radial resolutions that are now independent of eachother.
Set:

  nzones = #zones in 1d transport equations

  nzone_nb  = #zones in the Monte Carlo fast ion model
              (recommended: 20 zones or 60 zones with smoothing).

  nzone_fp  = #zones in the Fokker Planck fast ion model.
              (recommended: 20 zones; default "dxfsmoo" smoothing
              control will avoid "step-function" behavior of heating
              profiles when nzones > nzone_fp).

  nzone_fb  = #zone rows in fast ion distribution function
              (default value: 10, alternate value of 20 now allowed).

Note: nzones/nzone_fb, nzone_nb/nzone_fb and nzone_fp/nzone_fb must
ALL be integers.

Example:  nzones=20, nzone_nb=20, nzone_fp=20, nzone_fb=10 (these
are the default settings).

It is recommended to use DXBSMOO=0.05 at least to smooth Monte Carlo
output profiles when using nzone_nb > 20 zones.

For fppmod, DXFSMOO controls radial smoothing of all output profiles;
the default value of DXFSMOO, -1, causes profile smoothing over a
range of +/- (1/nzone_fp), when nzone_fp << nzones -- this cleans up
step function like behavior of heating profiles.  Alternatives:

  DXFSMOO=0.0  suppresses smoothing
  DXFSMOO=0.05 sets constant smoothing regardless of values of
               nzones and nzone_fp.

However, the default is recommended (dmc 1 Nov 2002).

4 ION_PWR_BALANCE
[This section refers to non-PTRANSP separate solution for Ti(x,t) --
see PTRANSP section for coupled {Te,Ti,Pphi,density} solution options].

In TRANSP the ion temperature profile is evaluated by solving the
ion power balance equation -- unless NLTIPRO=.TRUE. is set (see
TRANSPHELP OPER NAMELIST ION_TEMP).  Two free parameters are 
available for adjustment of the Ti prediction:
  ion particle confinement Tau(p) - see ptcl balance
  ion conduction
These parameters do not always have leverage (some power balances
are dominated by other terms e.g. ion electron coupling).

Ion conduction is specified in the form
  (anomalous multiplier) * (fit to neoclassical ion conduction)

use NKIMOD to choose the fitting procedure (cf source/balcor/kapai.for):
  NKIMOD=2:  Hazeltine - Hinton fit
  NKIMOD=3:  Ware - Bolton fit
  NKIMOD=4:  Chang - Hinton fit
  NKIMOD=5:  as 4 with impurities correction

The anomaly factor XKFAC may be specified directly in the namelist
  (XKFAC=1.0 means use the neoclassical fit "as is"), or...

specify NLXKFI=.TRUE. in TRANSP namelist, set 
  PREXKF, EXTXKF in TRDAT namelist, to name a UFILE containing 
the value of the XKFAC multiplier as a function of time, or...
(new Aug 1986) set with NLXKFI the TRDAT values PREKF2 and EXTKF2
to read a 2d UFILE containing conductivity multiplier *profiles*
vs. time., or ...

set NKIMOD=0 and specify a 2d UFILE using PREKI2/EXTKI2 that
contains conductivity (cm**2/sec) chi(i) profiles vs. time, or...

use FEEDBACK to ion temperature scalar data.  This is described 
in the section on ION_TEMPERATURE.  AUG 1986 *** this latter 
feature has been expanded to support ION TEMPERATURE PROFILE
input data.  ... or ...

(New AUG 1986)
(use of NLXKIE and XKFAC together added Nov 1987)

set the switch NLXKIE=.TRUE. to set 
  ion conductivity = XKFAC * electron conductivity.  
This is implimented via a neoclassical conductivity multiplier
profile, so the controls

XKFMIN = minimum allowable conductivity multiplier (must be .GE.0.)
XKFMAX = maximum allowable conductivity multiplier

may be important.

And another option (Feb. 1995):  set NKIMOD=10 for the IFS-PPPL
Gryokinetic/Gyrofluid model fit (source/balcor:gkf_link.for, see
subtopic) which may be used to specify chi(i) in the interior
region of the plasma, xi=0.0 to xi=XIMAXGKF.  XIMAXGKF defaults
to 0.8; use XIMAXGKF=1.01 to apply the GKF model over the entire
plasma.

  *** KI2 input data must be supplied to specify chi(i) for the
      boundary region, xi > XIMAXGKF.

NKIMOD=10 may also be specified for a restricted time window,
using the time dependent controls.

And additional options:

NKIMOD=11 for Rebut-Lalia-Watkins (RLW) chi(i) predictive model
[P.H. Rebut, et al., Phys. Fluids, B3,(1991)2209.

NKIMOD=12 for RLW model with Boucher's modification of chi(i)
to Bohm-like, as per Rosenbluth 1994 IAEA-CN-60/E-P-2

5 KAPISN
DMC Oct 2010: New options for "aspect ratio" neoclassical fits:

Kinsey et al extracted the legacy TRANSP aspect ratio neoclassical
fit routine, added an argument list and removed its dependency on
TRANSP "common", made some corrections and published it in 2001 as 
the KAPISN NTCC module (see http://w3.pppl.gov/NTCC).  This has now 
been installed back into TRANSP as an option and can be activated by 
setting 

  NOPT_KAPISN = 1  -- run KAPISN with istringer=1 correction
  NOPT_KAPISN = 2  -- run KAPISN with no istringer correction
  NOPT_KAPISN = 0 (the default) -- run legacy TRANSP model

The istringer=1 correction substantially reduces chi(i) peaking on
axis but has no effect outside (r/a) =~ 0.15.

Based on limited testing using DIII-D data, TRANSP legacy and KAPISN 
(no istringer correction) seems to match well for:
  NKIMOD=2:  Hazeltine - Hinton fit
  NKIMOD=3:  Ware - Bolton fit
  NKIMOD=4:  Chang - Hinton fit

TRANSP is lower than KAPISN by a factor of 2 for 
  NKIMOD=5:  as 4 with impurities correction
    with the more recently checked code in KAPISN.

NKIMOD=1 and NKIMOD=6 fits will also run but with TRANSP numbers
running a factor of two or so higher than those of KAPISN.

NOTE on implementation:
-----------------------

Results are sensitive particularly to the definition of the q
profile and the relationship of |B_phi| and |B_pol| assigned to
flux surfaces.  For each flux surface TRANSP uses 

   |B_phi| = |R*B_phi|/R0MP
   |B_pol| = 2*pi*Lpol/|dVol/dPsi|
   q = (|B_phi|*rMP)/(|B_pol|*R0MP)

where (R*B_phi) is the para/diamagnetically corrected R*toroidal field 
that is constant on the flux surface, R0MP is the major radius half way
between the flux surface midplane intercepts, rMP "minor radius" is half
the distance between the flux surface midplane intercepts, Lpol is the 
poloidal pathlength around the flux surface, and dVol/dPsi is the 
derivative of enclosed volume with respect to the poloidal flux 
function Psi (B_pol = grad(Psi)/R).  To get good agreement between 
the NKIMOD=2,3,4 TRANSP legacy formulas and KAPISN, it is necessary
to define q as above.

Some of the available RPLOT Multigraphs:
  NCFKI_KAP show all available KAPISN fits (istringer=1);
  NCFKI_RJ* all versions of Rutherford-Julich fit, NKIMOD=1
  NCFKI_HH all versions of the Hazeltine-Hinton fit, NKIMOD=2
  NCFKI_B all versions of the Ware-Bolton fit, NKIMOD=3
  NCFKI_CH all versions of the Chang-Hinton fit, NKIMOD=4
  NCFKI_CH2* all versions of modified Chang-Hinton, NKIMOD=5
  NCFKI_CHZ* all versions of modified Chang-Hinton, NKIMOD=6

*DIII-D tests indicate factor ~2 differences in the results

NOPT_KAPISN cannot be changed or steered as a function of time, and
so is either set or not for the entire TRANSP run.

5 GKF_MODEL
The following is a set of references for the IFS-PPPL
Gryokinetic/Gyrofluid transport model that gives predictions
for chi(i) and chi(e), available in TRANSP:

W. Dorland, M. Kotschenreuther, M.A. Beer, G.W. Hammett, et.al.,
"Comparisons of Nonlinear Toroidal Turbulence Simulations with 
Experiment", in Plasma Physics and Controlled Nuclear Fusion 
Research 1994, (to be published by the IAEA, Vienna, 1995).

M. Kotschenreuther, W. Dorland, M.A. Beer, G.W. Hammett, 
to be published in Physics of Plasmas, 1995.

M.A. Beer, "Gyrofluid Models of Turbulent Transport in 
Tokamaks", Ph.D. Thesis, Princeton, 1994.

5 ETA_I_MODEL
(This model is now considered obscolescent; not carried forward into
PTRANSP).

TRANSP now has an ETA_I model for enhanced ion conduction.  It is 
based on the formulae by Pat Diamond et al, as coded in 
source/balcor/ketai.for.

The model involves a very large ETA_I=infinity limit ion thermal
diffusivity, and a switching function, where, if 
  ETA_I = d(ln Ti)/d(ln ni)
is less than some value, there is no enhancement of conductivity; 
if greater than some larger value, full ETA_I=infinity enhancement
applies, with a smooth transition for intermediate values.

WARNING.  THIS MODEL IS NOT CODED IMPLICITLY IN THE TI-TIMESTEP 
ADVANCE.  THUS THE SOLUTION WILL BE UNSTABLE UNLESS SHORT TIMESTEPS
ARE EMPLOYED; SET
  DTMAXT=0.05E-3
  DTINIT=0.05E-3
IN THE NAMELIST.

ETA_I model controls:

NLKETI=.TRUE. for ETA_I model (default .FALSE.)
XKFETI= anomalous enhancement factor for ETA_I chi(i) (default =1.0)
ETAITH= **base critical ETA_I**  see also ETAIMU, ETAIM0 
        (default =2.0)
ETAISW= **ETA_I mode switching window half-width**  (default =0.5)
ETAIMU= "Romanelli" multiplier for large density scale length regions
        (default =0.0, typical value used =4.5)
ETAIM0= "Romanelli" scale length offset  (default =0.3)
NETIDN= density definition control (default =1:  use ion density)
        set =2 to use electron density instead.  Note:  grad(ni) can
        go to zero and is generally problematic, especially in low
        density beam dominated cases.

Above switches work as follows:
ETA_Icrit = ETAITH + max(0,ETAIMU*(Ln/R - ETAIM0))
  where Ln= density scale length; R = magnetic axis location, cm

No conductivity enhancement if ETA_I .le. ETA_Icrit - ETAISW
ETA_I=infinity enhancement  if ETA_I .ge. ETA_Icrit + ETAISW

if inbetween:  transitional enhancement, defined by a switching
function f(ETA_I) = a cubic with zero slope at both bdy's, value
0.0 at the lower bdy and value 1.0 at the upper bdy.
5 CONVECTION

set ALPH0I to define ion convection power loss as

  Pconvi = ALPH0I * 5/2 * div( n*k*T*<v_radial> ) (for ions)

Note that ALPH0I=1.0 is the default.

there are also controllable J X B terms-- considered part of 
convection as they are tied to avg radial velocity <v_radial> which is
output of the particle balance calculation.  Normally these terms
are off:
  ALPHAE=ALPHAI=0.0

5 TIME_VARYING_CHI_I_MODEL
(New DMC 14 Aug 1991)
The namelist arrays NKIMODA, TKIMOD, and XKIMOD may be used to set up
different chi(i) "regimes" at different times during the run.  Up to
eight different time regimes may be specified.

These regimes involve changing the settings of NKIMOD, XKFAC, NLTI2,
NLTI2TX, and NLXKIE, defined elsewhere in the HELP file.

Set TKIMOD(j) to be the time of transition from regime j to j+1.  If
TKIMOD is used at all, TKIMOD(1) must be .GT. 0.0 and all TKIMOD
values specified must be in strict ascending order.

Use NKIMODA(j) to specify the chi(i) regime:

   NKIMODA(j)= 1,2,3,4,5, or 6 to specify a neoclassical chi(i) model
     NKIMOD gets set to NKIMODA(j); NLTI2=.FALSE; NLXKIE=.FALSE.
   NKIMODA(j)= -1,-2,-3,-4,-5, or -6 to specify a neoclassical model
     with multiplier feedback to match Ti profile input data.  Input
     data must have been supplied.
     NKIMOD gets set to abs(NKIMODA(j)); NLTI2=.TRUE.; NLXKIE=.FALSE.
       if NLTI2TX=.TRUE., impurity temperature is matched.
   NKIMODA(j)= 0 to use chi(i) Ufile input data -- must have been
     supplied.
     NKIMOD gets set to 0; NLTI2=.FALSE.; NLXKIE=.FALSE.
   NKIMODA(j)=99 to use chi(i)=XKFAC*chi(e)
     NKIMOD gets set to 4; NLTI2=.FALSE.; NLXKIE=.TRUE.

   for the time interval ending at TKIMOD(j),
     XKFAC=XKIMOD(j) is set if NKIMODA(j).gt.0

   NKIMODA(j)=100 to switch from Ti prediction to Ti *analysis mode*
     during the indicated time interval.  See Ion_Temperature topic.
       if NLTI2TX=.TRUE., a correction is applied to the data to
       reflect the difference btw impurity temperature and bulk
       temperature (see ION_TEMP topic).

   NKIMODA(j)=10,11,12,... for chi(i) predictive model options,
     as described for NKIMOD under TRANSPHELP OPER NAMEL ION_PWR_BAL.
Example:

   TINIT=2.0
   TKIMOD=2.1,2.5
   NKIMODA=4,99,-4
   XKIMOD=5.0,2.0

Has this effect:

   chi(i) is 5 * Neoclassical (Chang-Hinton) from 2.0 to 2.1 seconds.
   chi(i) is 2 * chi(e) from 2.1 to 2.5 seconds.
   chi(i) is set to match input profile Ti data from 2.5 seconds on.

Use of TKIMOD(...) is not permitted if scalar Ti data is being used
to adjust XKFAC vs. time (NLFXKF=.TRUE.) or if a time dependent scalar
XKFAC Ufile is input (NLXKFI=.TRUE.)
5 Boundary_Conditions
Namelist controls determine the setting of the boundary condition for
the ion temperature prediction.  The controls are:

  MODIEDG -- boundary condition option select (btw 1 and 5 inclusive)
  MOD0ED  -- boundary condition option for recycling neutrals

these parameters are only used for certain option settings:
  TIEDGE  -- edge temperature setting
  TI0FRC  -- central temperature multiplier

options:  

MODIEDG=1  ==>  use the same boundary condition for the edge ion
  temperature as for the recycling neutrals at the edge.  This is
  the default.
MODIEDG=2  ==>  use TIEDGE namelist input as boundary condition
MODIEDG=3  ==>  use edge electron temperature data as bdy cond.
MODIEDG=4  ==>  use edge ion temperature data as bdy cond.
MODIEDG=5  ==>  use NTCC PEDESTAL module to determine bdy cond.

The following also applies to edge ions if MODIEDG=1:

MOD0ED=1   ==>  use TIEDGE for the recycling neutral energy at the
  plasma boundary.  This is the default.
MOD0ED=2   ==>  use TI0FRC*Ti(center) for the recycling neutral energy
  at the edge (not available for PTRANSP runs)
MOD0ED=3   ==>  use edge electron temperature data as bdy cond.
MOD0ED=4   ==>  use edge ion temperature data as bdy cond.

TIEDGE defaults to 10.0 eV.  Subroutine reference:  balcor/tibdy.for

To activate the PEDESTAL controls set

MODEEDG = 5	!Use PEDESTAL module for the electron temp. profile
MODIEDG = 5	!Use PEDESTAL module for the ion temp. profile

in the namelist input.

6 Pedestal_Model

H-mode pedestal parameters can be controlled either from namelist input
or by use of the NTCC pedestal model.

Pedestal controls are "steerable"; this means that an ascending sequence
of "~update_time = <time-value>" blocks can be used in a TRANSP input 
namelist, to specify different controls over different blocks of time:

Thus:

  <main namelist>
  ...<initial pedestal controls>
  ~update_time = <time1>
  ...<1st update pedestal controls>
  ~update_time = <time2>
  ...<2nd update pedestal controls>

In this pseudo-example, <initial pedestal controls> are in effect from
TINIT to <time1>; <1st update pedestal controls> from <time1> to <time2>,
and <2nd update pedestal controls> from <time2> to FTIME.

The following controls determine which pedestal parameters to control 
from the namelist, and which from the NTCC pedestal module:

 ~I 0  NMODEL_L2H_TRANS = 1   ! L-H transition model choice:
                       !    =1: NTCC Pedestal module
                       !    =0: steerable namelist input (below)

  ! for predictive boundary conditions:
  ! in general, pedestal values are used in H mode, and trdat data or 
  ! namelist values (TIEDGE etc.) are used in L mode

 ~I 0  NMODEL_PED_HEIGHT = 1   ! Pedestal height model choice:
                       !  Pedestal heights for Te, Ti, ne
                       !    =1: NTCC Pedestal module (if it indicates H mode
                       !        otherwise use namelist values).
                       !    =0: steerable namelist input values (below).

 ~I 0  NMODEL_PED_WIDTH  = 1   ! Pedestal width model choice:
                       !  Pedestal widths for Te, Ti, ne
                       !    =1: NTCC Pedestal module (if it indicates H mode
                       !        otherwise use namelist values).
                       !    =0: steerable namelist input values (below).

This control limits the time rate of change of boundary conditions, whether
from input data or due to L to H transitions.
 ~D 0  TAU_LH_TRANS_X2 = 0.005d0 !  minimum time (s) for factor of 2 change in 
                       !  boundary condition parameters (temps or densities).
                       !  NOTE (DMC Aug 2009): this is now applied even to 
                       !  non-H-mode boundary condition data for Te, Ti, ne,
                       !  and angular velocity...
 
7 NTCC PEDESTAL module

The PEDESTAL module installed in the PTRANSP code can be accessed using
the edge model namelist variables MODEEDG (electrons) and MODIEDG (ions).
The PEDESTAL module, along with its interface to p-TRANSP will

a) Carry out an automated L-H transition when the heating power rises
   above the computed threshold power.
b) Supply the electron and/or ion power balance subroutines with the 
   width and height of the H-mode pedestal.
c) Carry out an automated H-L transition when the heating power drops
   below the computed threshold power.

Experimental data will be used when the heating power is below the
threshold power (equivalent to MODEEDG = 3, MODIEDG = 4).

The NTCC pedestal module predictions can be scaled, with these controls:

 ~D 0  SCALE_TEPED = 1.0d0  ! Scale factor for Te pedestal height -- only used
                       ! if NMODEL_PED_HEIGHT > 0.

 ~D 0  SCALE_TIPED = 1.0d0  ! Scale factor for Ti pedestal height -- only used
                       ! if NMODEL_PED_HEIGHT > 0.

 ~D 0  SCALE_NEPED = 1.0d0  ! Scale factor for ne pedestal height -- only used
                       ! if NMODEL_PED_HEIGHT > 0.

7 Namelist_Pedestal_Controls

These apply to the extent that pedestal parameters are selected to be 
controlled from the namelist and NOT from the NTCC pedestal model:

 ~D 0  TIME_L2H = 0.0d0 !  time (s) of transition from L mode to H mode
                       !  (for NMODEL_LH_TRANS = 0)
                       !  (Note: code always starts in L mode).

 ~D 0  TIME_H2L = 0.0d0 !  time (s) of transition from H mode to L mode
                       !  (for NMODEL_LH_TRANS = 0)
                       !  (ignored if plasma in L mode when time is reached).

 ~D 0  TEPED  =  100.0d0 !Electron pedestal temperature in eV
                       ! (for NMODEL_PEDESTAL = 0)

 ~D 0  TEPEDW  =  0    !Electron pedestal width in cm (+) or x (-)
                       !use negative value to express width in sqrt norm tflux
                       ! zero means: top of pedestal value assigned at boundary

 ~D 0  TIPED  =  100.0d0 !Ion pedestal temperature in eV
                       ! (for NMODEL_PEDESTAL = 0)
 
 ~D 0  TIPEDW  =  0    !Ion pedestal width in cm (+) or x (-)
                       !use negative value to express width in sqrt norm tflux
                       ! zero means: top of pedestal value assigned at boundary

 ~D 0  XNEPED  =  1.0d12 !Electron pedestal DENSITY in cm**-3
                       ! (for NMODEL_PEDESTAL = 0)

 ~D 0  XNEPEDW  =  0   !Electron density pedestal width in cm (+) or x (-)
                       !use negative value to express width in sqrt norm tflux
                       ! zero means: top of pedestal value assigned at boundary

Note: some PTRANSP predictive options may require TEPEDW = TIPEDW = XNEPEDW;
the ability to actually use different pedestal widths for different plasma
parameters may be added later (comment DMC Dec. 2009).

4 ELEC_PWR_BALANCE
IN TRANSP the evolution of electron temperature and density are usually
specified as input.  Therefore the electron power balance equation is
solved to deduce the amount of electron heat conduction consistent with
the observed data:
  electron conduction = heat input - d/dt(electron energy)
                          - other losses

"other losses" are primarily convection (see ptcl balance) and
radiation (see power radiated).  Obviously, any error in the
RHS of this equation are mapped right over to the LHS.

TRANSP has the ability to PREDICT electron temperature.
Use the TRANSP namelist controls NKEMOD, etc., to specify electron
heat conduction.  See subkey Te_prediction below...

WARNING:  In order to solve for electron temperature,
POWER RADIATED must be specified for input and MUST
BE "CORRECT".  Since there is no physical model for radiated power
in TRANSP, radiated power will not drop if the electron temperature
drops, so the electron temperature at some radius could continue
to fall until it becomes negative, in which case the code crashes.

TRANSP contains a variety of electron conduction simulators, but there
there are no models for power radiated, nor for electron density profile
evolution.  Thus another code e.g. BALDUR is probably better suited
for simulation work in most cases.
5 Te_prediction
TRANSP Te prediction options are controlled by the following namelist
arrays:

NKEMOD(j)  prediction option for time region j =1,2,3,...,8
  NKEMOD(j)=0 -- **analysis mode** Te data is not predicted; use
    measured Te data.
  NKEMOD(j)=-2 -- **use KE2 UFILE data** to specify conductivity
    See also TRDAT namelist re KE2 data!  And set:
      NLXEIN=.TRUE. to request readin of KE2 data
      XKEMIN,XKEMAX = min, max acceptable diffusivities (reasonable
        defaults are set in source/freeshare/port.for) from KE2 data.
        A negative diffusivity may destabilize the Te prediction.
  NKEMOD(j)=-1 -- **freeze conductivity profile** to its current 
    value; use this option for j.gt.1 only.
  NKEMOD(j).gt.0 -- select theoretical conductivity model -- see 
    KAPAE.FOR

  NKEMOD(j)=10 for IFS-PPPL Gyrokinetic/Gyrofluid model fit (in
    source/balcor:gkf_link.for) -- this fit only covers the
    region xi=0.0 to xi=XIMAXGKF; NLXEIN=.T and KE2 data must
    be supplied to specify chi(e) in the boundary region 
    xi.gt.XIMAXGKF..  XIMAXGKF defaults to 0.8; use XIMAXGKF=1.01
    to apply the GKF model over the entire plasma.  
    ...For GKF references:  see subtopic GKF_MODEL.

  NKEMOD(j)=11 or 12 for Rebut-Lalia-Watkins (RLW) chi(e) 
  predictive model.
  [P.H. Rebut, et al., Phys. Fluids, B3,(1991)2209.

TKEMOD(j)  transition time-- time to switch from prediction option
  NKEMOD(j) to NKEMOD(j+1).  NOTE transition from prediction to 
  analysis mode is not permitted as it implies a discontinuity in
  electron temperature.
XKEMOD(j)  anomalous multiplier to apply to theoretical model used
  for electron conductivity in time region j.

Defaults:  
  TKEMOD(i)=0.0 for all i, so that there is only one time region
for the entire run, controlled by NKEMOD(1) and XKEMOD(1).
  XKEMOD(i)=1.0 for all i
  NKEMOD(i)=0 (no prediction, use standard analysis mode)
6 GKF_MODEL
The following is a set of references for the IFS-PPPL
Gryokinetic/Gyrofluid transport model that gives predictions
for chi(i) and chi(e), available in TRANSP:

W. Dorland, M. Kotschenreuther, M.A. Beer, G.W. Hammett, et.al.,
"Comparisons of Nonlinear Toroidal Turbulence Simulations with 
Experiment", in Plasma Physics and Controlled Nuclear Fusion 
Research 1994, (to be published by the IAEA, Vienna, 1995).

M. Kotschenreuther, W. Dorland, M.A. Beer, G.W. Hammett, 
to be published in Physics of Plasmas, 1995.

M.A. Beer, "Gyrofluid Models of Turbulent Transport in 
Tokamaks", Ph.D. Thesis, Princeton, 1994.

5 CONVECTION

set ALPH0E to define electron convection power loss as

  Pconve = ALPH0E * 5/2 * div( n*k*T*<v_radial> ) (for electrons)

Note that ALPH0E=1.0 by default.

there are also controllable J X B terms-- considered part of 
convection as they are tied to avg radial velocity <v_radial> which is
output of the particle balance calculation.  Normally these terms
are off:
  ALPHAE=ALPHAI=0.0

5 Boundary_Condition
The following controls are used to determine the Te boundary
condition when the Te profile is being predicted:

MODEEDG -- boundary condition option
TEEDGE  -- boundary condition parameter

options:

MODEEDG=2 ==> use TEEDGE to specify the edge electron temperature
MODEEDG=3 ==> use Te input data to specify the edge electron
  temperature.  This is the default.
MODEEDG=5 ==> use NTCC PEDESTAL module to compute bdy. condition.
  (see subsection for PEDESTAL module above-- in discussion of 
  ion power balance boundary conditions).

the default TEEDGE is 10.0 eV.  Subroutine ref:  balcor/tebdy.for
4 Electrostatic_Field
The Er field is closely linked to plasma rotation.  For details on
options for specifying the Er field in TRANSP, see the neighbouring
section on rotation.
4 ROTATION
The TRANSP rotation model can now be used in either the
traditional analysis mode, or in predictive mode.

Time switching is also allowed btw analysis and prediction,
and btw the various predictive chi(phi) models.
5 Analysis
Rotation modeling is available in 1987.

Specify NLVPHI=.TRUE. and supply a rotation rate UFILE to TRDAT,
either axial rotation speed vs. time (1d UFILE-- PREVPH,EXTVPH)
or rotation speed profiles vs. time (2d UFILE-- PREVP2,EXTVP2) or
rotation angular velocity profiles vs. time (2d UFILE-- PREOMG,
EXTOMG).

** SIGN CONVENTION FOR ROTATION DATA **

Positive rotation rates or velocities indicate rotation in the 
direction of the plasma current (or equivalently, the direction 
of beam "CO-injection"); negative rotation rates or velocities
indicate rotation against the current (or in the direction of
beam "CTR-injection").

If both timeseries and profile data are available, the profile
data may be "renormalized" to the timeseries data by specifying
both input Ufiles to TRDAT and setting the switch NLRNVP to .TRUE.;
then set RMJRVP = major radius at which to perform renormalization;
if RMJRMP is defaulted the renormalization occurs at the midpoint
of the plasma midplane intersection.  This works whether the input
profile is in units of rotation speed (cm/sec) or angular velocity
(rad/sec).

If only axial rotation speed is provided, use the namelist variable
XVPHI to control the shape of the assumed angular velocity profile
used in the analysis.  For details-- see code in subroutine GOMEGA.

see information in the TRDAT namelist help section.

dmc 18 Sep 1998 -- neoclassical upgrade -- toroidal or poloidal
rotation profile data may now be entered for a single plasma
species.  The profile trigraphs are:

  VTR -- (preVTR,extVTR, etc.) -- toroidal rotation velocity 
         profile, cm/sec
  VPR -- (preVPR,extVPR, etc.) -- poloidal rotation velocity
         profile, cm/sec

The plasma specie is identified by the namelist scalars:

  NGVTOR -- VTR species -- 
    = 101 for impurity (default)
    =  -1 for electrons, 
    = ig, ig between 1 and ngmax, for ion specie
    = 0 -> species is identified by atomic number NVTOR_Z
           and atomic weight XVTOR_A (NCMODEL=2 only)
  NGVPOL -- VPR species -- 
    = 101 for impurity (default)
    =  -1 for electrons, 
    = ig, ig between 1 and ngmax, for ion specie
    = 0 -> species is identified by atomic number NVPOL_Z
           and atomic weight XVPOL_A (NCMODEL=2 only), the 
           poloidal data will not be used in nclass unless the 
           poloidal species matches the toroidal species

In addition, the switch NLOMGVTR can be used to specify that
traditional rotation profile data (OMG or VP2 data) really gives
the diagnostic ion velocity profile.

The switch NVMO_OPTION can specify a momentum pinch term which is 
proportional to chi(phi)-- and so affects the chi(phi) output 
where the momentum equation is analyzed from input angular 
velocity data.  Details are given in separate sections, below.

5 Neoclassical_Interpretation
(new dmc 18 Sep 1998) -- this section describes a new variant
for analysis of rotation velocity measurements, with enhanced
physics.

Rotation velocity input data may now be interpreted using the
general geometry neoclassical code NCLASS -- as described in
TRANSPHELP OPERATIONS NAMELIST NCLASS section.

To get this, set

  NLVWNC = .TRUE.

and provide species specific toroidal velocity data (either a
VTR Ufile or traditional data with NLOMGVTR=.TRUE. set, see
neighbouring section on rotation velocity profile analysis).

This mode of operation results in solving for the radial
electrostatic potential using the neoclassical model and data
for one ion species.  The resulting potential is applied to
the other species, determining their rotation profiles as well.

An angular inertia weighted average is used to give the
angular velocity profile used for momentum balance purposes
(and for defining the target e.g. for the beam deposition
calculation).  If not overridden by VPO data, the electrostatic
field derived from the neoclassical interpretation is also used
in fast ion orbit calculations.

Note that due to model and data limitations the full NCLASS 
interpretation is applied only over the plasma in the range
XL1NCVPH .le. r/a .le. XL2NCVPH.  Flat extrapolation is
applied from XL1NCVPH in to the axis; from XL2NCVPH out
the rotation magnitude is not allowed to become greater
than the value at XL2NCVPH; the defaults for these controls
are

  XL1NCVPH=0.10
  XL2NCVPH=0.85

When NLQLIM0 is being used, then the lower limit is applied from
the edge of the Q limited region.

Note: NLVWNC can be used in predictive runs; in this case the 
predicted angular velocity is used unmodified and the NCLASS
output only modifieds the radial electrostatic field (see next
section).

5 Electrostatic_Field

(new section 18 Sept 1998)
(modified DMC 22 July 2010)

Traditionally, TRANSP set the radial electrostatic potential, used
in the fast ion orbit model, from toroidal rotation data input using a
"zero'th order" formula derived from an assumed force balance between 
the rotational flow induced vt x Bp Lorenz force and the force due to 
the electrostatic field.

A control has been added that would allow some variations on this 
"zero'th order" treatment are now available, set by NOPTION_ERADIAL.
See the subtopic.

Now, by setting 

  NLVWNC = .TRUE.,

The neoclassical corrections are taken into account in the
evaluation of the electrostatic field.  In analysis mode
this is based on solving a neoclassical expression using
velocity profile data input (usual toroidal impurity ion
velocity).  In predictive mode, a similar equation is
solved which is based on an angular inertia weighted sum
over thermal ion species.

A final option is to input the radial electrostatic potential
(in volts) directly, using the VPO Ufile (set preVPO, extVPO,
etc.), and set the switch

  NLIVPO = .TRUE.

to specify the potential given in the input data as the one
to use e.g. for fast ion modeling.  If NLIVPO = .FALSE. the
VPO data is read but not used, only passed on to output
for comparison with the neoclassically derived radial 
electrostatic potential.

NLVWNC and NLIVPO cannot BOTH be set.

Summary: the radial electrostatic potential and field can either be
set by the simplified "zero'th order" Lorentz force balance, with
options set by NOPTION_ERADIAL, ...or... set by the NCLASS neoclassical
analysis (NLVWNC=.TRUE.) ...or... set by input data (NLIVPO=.TRUE.).

6 NOPTION_ERADIAL

Here are the options for "zero'th" order Lorentz force balance analysis:

NOPTION_ERADIAL=0 (** this is the default **) -- estimate radial 
electrostatic potential from toroidal velocity only, assuming local
balance of vphi x Bpol by radial electrostatic field.

As of July 2010 this is the only option

  rho = sqrt toroidal flux based radial flux coordinate
  Philim = enclosed toroidal flux (Wb) at plasma boundary
  Phi(rho) = rho**2*Philim -- by definition of rho
  dPhi = 2*rho*Philim*drho

  Vpo(rho) = radial electrostatic potential (volts)

  psi(rho) = enclosed poloidal flux function, Wb/rad

  omega(rho) = toroidal angular velocity
    [sign convention: positive value denotes rotation in same
     direction as plasma current]

    local field: Bpol = grad(psi)/R = dpsi/drho * grad(rho)/R
    local toroidal velocity: vtor = R*omega
    local vtor x Bpol = -omega * grad(rho) * dpsi/drho
      (inward for omega > 0)

    Er = -vtor x Bpol = omega * grad(rho) * dpsi/drho
      (outward for omega > 0)

    Er = -grad(Vpo) = -d(Vpo)/drho * grad(rho)
      (Vpo higher on inside, for outward Er)

  d(Vpo)/drho = -omega*dpsi/drho
              = -omega*rho*Philim/(q*pi)
      (for positive omega, Vpo is increasing to the inside).

  q(rho) = 1/iotabar = rotational transform = dPhi/(2*pi*dpsi)

  Vpo is integrated inward assuming Vpo=0 volts at the boundary.

  There is no contribution from poloidal velocity!

Future NOPTION_ERADIAL values could be added to make use of poloidal
velocity data x toroidal field data.

For example, new NOPTION_ERADIAL values could introduce a term due
to poloidal rotation velocity:

Note: NOT IMPLEMENTED as of July 2010

  (sign convention, +vpol means velocity upward on outer half midplane)
  input data Vpol_omp(rho) = velocity on outer half midplane

  Fpol = Vpol_omp*(2*pi*R*dR/drho) on outer half midplane
    around flux surface, Vpol = Fpol*grad(rho)/(2*pi*R)

  IBCCW = +1 if Bphi points counter-clockwise viewed from above
          -1 if otherwoise

    Bphi = IBCCW*(g/R)
    Vpol*Bphi = IBCCW*g*Fpol*grad(rho)/(2*pi*R**2)

  d(Vpo)/drho = -IBCCW*g*Fpol*<1/R**2>/(2*pi) ! due to Vpol only

  (IBCCW = +1 and Vpol_omp positive => Vpo increasing towards inside).

Note: NOT IMPLEMENTED as of July 2010

5 Momentum_convection

(Used both in analysis and prediction)

  d[Momentum]/dt = Sources -
                   del.[(viscous transport) + (convective transport)]

(The terms "advection" and "pinch velocity" are also used to refer to
what is called convection here).

Historically, the code has inferred the convective transport from the 
particle balance; it is assumed in this case that the radial velocity of 
momentum is the same as that of particles inferred from particle balance.
The following modifications are available:

   XVPHI_PBAL = <some number other than 1.0>
     ! (default value 1.0): multiply the particle balance velocity
     ! by this number to get the momentum velocity.

   PREVMO/EXTVMO  (time dependent profile Ufile input)
     ! impose a momentum velocity input profile, which is added to
     ! XVPHI_PBAL*[particle balance velocity]; use XVPHI_PBAL=0.0
     ! to use the PREVMO/EXTVMO data exclusively.  Default is
     ! XVPHI_PBAL = 1.0.
     !   NOTE: PREVMO/EXTVMO not used if a theory-based predictive
     !         transport model is specified for momentum
     !         (generally NVPHMOD or NVPHMODA(...) .ge. 11)

   NVMO_OPTION = <a non-negative integer>
     ! (default 0) if greater than 0 provide a theory based expression
     ! for the convective transport term (available models below).
     ! (the computed quantity often called a "pinch velocity").

     ! NOTE: if a pinch term is selected which has dependence on 
     !   momentum diffusivity, the inferred diffusivity will be
     !   affected at times and in regions where the angular velocity
     !   profile is input and the momentum transport is output of the
     !   analysis.

   XFACTOR_NVMO = <a positive number O(1.0)>
     ! (default value 1.0): constant multiplier, applied to output
     ! of pinch model selected by NVMO_OPTION

In addition, in a predictive simulation, a transport model could provide
a convective momentum term (as of Aug. 2010, only MMM08 does this).  If 
so, a multiplier on this term can be specified in the namelist:

   XFACTOR_THMOD_VMO = <a positive number O(1.0)>
     ! (default value 1.0): constant multiplier, applied to output
     ! of selected predictive transport model model selected e.g. by 
     ! NVPHMOD or NVPHMODA(...)

The net convective velocity or pinch is then:

  XVPHI_PBAL*[that inferred from ptcl bal]
 + phi(th)*[that read in from PREVMO/EXTVMO input data]
 + XFACTOR_NVMO*[pinch model specified by NVMO_OPTION]
 + XFACTOR_THMOD_VMO*[predictive transport model flow term]

Where phi(th)=1 for ad hoc momentum transport models and phi(th)=0
for theory based models NVPHMOD or NVPHMODA(...) .ge. 11.

Namelist scalar factors: XVPHI_PBAL, XFACTOR_NVMO
Range restrictions: 0 <= XPHI_PBAL <= 10
                    0 <= XFACTOR_NVMO <= 10
                    0 <= XFACTOR_THMOD_VMO <= 10

These limits on the namelist inputs are enforced by "datchk".

6 RPLOT_output

The VMO multigraph contains:

  VMO_PBAL -- momentum radial velocity to be inferred from ptcl balance
  VMO_DATA -- Ufile input radial velocity (zero, if none provided)
  VMO_PINCH -- pinch velocity (zero, if none selected)
  VMO_THMOD -- predictive transport model velocity (may be zero)

  VMO_NET -- net radial velocity

    VMO_NET = XVPHI_PBAL*VMO_PBAL + phi(th)*VMO_DATA 
               + XFACTOR_NVMO*VMO_PINCH
               + XFACTOR_THMOD_VMO*VMO_THMOD

Where phi(th)=1 for ad hoc momentum transport models and phi(th)=0
for theory based models NVPHMOD or NVPHMODA(...) .ge. 11.

Namelist scalar factors: XVPHI_PBAL, XFACTOR_NVMO
Range restrictions: 0 <= XPHI_PBAL <= 10
                    0 <= XFACTOR_NVMO <= 10

These limits on the namelist inputs are enforced by "datchk".

6 Interpretation_of_velocity

For transport of angular momentum density n_M, as for other types of 
densities, velocity v satisfies the relation

   [total flow, M-units / second] = Surf * n_M * v

   v = [total flow] / (n_M * Surf)

   n_M = density, M-units/cm**3
   Surf = area of flux surface, cm**2
   n_M * Surf  has units  M-units/cm

   so, v has units cm/sec

Velocity inferred from particle balance is interpreted in these terms,
but the momentum dependency has a mass dependence and so the contribution
of impurities is more heavily weighted (i.e. compared to the relative
contribution of their convection in the ion power balance equation).

Velocity input data (preVMO/extVMO) is interpreted in the same way, i.e.

  [flow-due-to-input-data] = Surf * n_M * v_from_input_data

See also: VMO_DATA_DETAILS under the section on rotation prediction.

5 Prediction
Plasma rotation prediction is now an option of TRANSP.  However, a
chi(phi) model must be specified by setting the NVPHMOD switch to
a supported non-zero value:

  NVPHMOD=1   ...   to use chi(phi) profile input
                    a profile Ufile specified with TRDAT switches
                    PREKPH/EXTKPH; Also can use momentum pinch velocity
                    in Ufile PREVMO/EXTVMO -- if provided, add it to the 
                    scaled velocity inferred from particle balance (see 
                    scaling control XVPHI_PBAL)

  NVPHMOD=2   ...   to use chi(phi) = chi(i).
                    PREVMO/EXTVMO data also used if provided

  NVPHMOD=3   ...   to use chi(phi) = const. = XKPINP
                    PREVMO/EXTVMO data also used if provided

  NVPHMOD=4   ...   to use chi(phi) given by GLF23 or Weiland model
                       (same model as used for ion heat transport)
                    PREVMO/EXTVMO data NOT used -- theoretical model
                       is responsible for both the diffusivity and the
                       pinch velocity!

  NVPHMOD= 11, 12, 13, ...
                    various theory based predictive turbulent transport
                    models (under development)
                    PREVMO/EXTVMO data NOT used -- theoretical model
                       is responsible for both the diffusivity and the
                       pinch velocity!

  [NVPHMOD=0 is reserved for rotation analysis].
  [for NVPHMOD=0, PREVMO/EXTVMO data also used if provided; it modifies
   the convective term and hence the inferred viscous transport].

The chi(phi) selected can then be further multiplied by the factor
XKFVPH (default value:  1.0).  XKFVPH can be set time dependently,
see the neighbouring topic.

Related switches:

  XVPHI_PBAL ... (default value = 1.0): relation of momentum advection
                to radial flow inferred from particle balance; =1 means
                radial flow ptcls carry the "average" local angular
                momentum.  Set XVPHI_PBAL=0 and use the PREVMO/EXTVMO
                Ufile to control momentum radial advection, independent
                of the particle balance (continuity) equation.  The
                value of XVPHI_PBAL should be a non-negative number
                of order 1.0, or less.  If it is positive, and
                PREVMO/EXTVMO is set, the advective velocity from the
                data is added to the radial flow inferred from the 
                particle balance and adjusted by XVPHI_PBAL.

  CHPHIMIN  ... the minimum allowed chi(phi), cm2/sec
  CHPHIMAX  ... the maximum allowed chi(phi), cm2/sec

CHPHIMIN should be greater than 1.0 cm2/sec; a lesser value
will be replaced by this value.

  XPHIBOUND ... radial limit for prediction of toroidal rotation
                frequency

TRANSP will use experimental data for XI > XPHIBOUND. Default 
behavior is XPHIBOUND = 1.0, i.e. use experimental rotation 
frequency at the plasma edge. Note that XPHIBOUND is independent
of XIBOUND, i.e. the thermal and toroidal momentum equations
are solved using independent boundary conditions.

6 NVMO_OPTION

Options for radial momentum pinch -- affects both prediction and analysis,
if the pinch is dependent on chi(phi).

(Values not shown are unsupported and would cause an error condition)

NVMO_OPTION = 0 !(the default) means, no theoretical model contribution.

NVMO_OPTION = 1 ! Coriolis Pinch

  Vradial_Pphi/grad(x) = -alpha*chi(phi)*
             [4*(Ti/Te)/<R*grad(x)> + (1/n)*(dn/dx)]

  for n, the total ion mass density is used: sum[ni*mi]

             sqrt(eps)*(5 + q)
  alpha = -----------------------
            6*(1+(shat - 1)**2)

  eps = aspect ratio r/R, midplane definition, each flux surface

  q = 1/iota(bar) = rotational transform

  shat = (x/q)*(dq/dx)

  x = radial toroidal flux coordinate sqrt(Phi/Philim)

  Note that this pinch is proportional to radial momentum diffusivity
  chi(phi).  This effects the analysis, at times and in regions where
  angular velocity is input and chi(phi) is inferred from the momentum
  balance equation.

  The form is as developed in conversation with A. Field and F. Casson
  on the MAST project, with the following references cited:

     [1] PRL 98, 265003 (2007)
     [2] Phys. Plasmas 16, 062311 (2009)
     [3] Phys. Plasmas 16, 122302 (2009).

  Casson's description: this is an improved expression for Coriolis 
  pinch, including approximate parametric dependencies of linear kinetic
  results in [1] and [2].  This form captures the strongest dependencies
  of the kinetic linear results for an ITG mode, with a reasonable fit
  for the factor XFACTOR_NVMO=1.000d0.  This factor could be tweaked 
  for individual cases, but the closer it stays to 1, the better the
  theory.  The strength of the pinch is roughly halved for a trapped
  electron mode [3].  Of course, the most accurate determination of
  the pinch for any given case would require a full nonlinear
  gyrokinetic simulation.

The namelist factor XFACTOR_NVMO is applied to the computed pinch as a
multiplicative factor (default value of XFACTOR_NVMO is 1.000d0).

6 VMO_data_details
(Copy of email 8 Oct 2007)

Wayne,

OK, I looked...  Per Goldston's paper, discussion after equation 7, local 
particle fluxes are assumed proportional to the local driver gradients e.g. 
perhaps of n, i.e.   v ~ konst*grad(n) ~ konst*(dn/drho)*grad(rho).  With 
the drivers such as n still assumed to be flux surface constants, the flux 
surface constant associated with radial velocity is [v/|grad(rho)|].  In 
terms of particle fluxes, the total flow, #/sec across a surface, is then 
given by:

   FLOW = [v/|grad(rho)|]*n*(2*pi)*integral(dl*R*grad(rho))
        = [v/|grad(rho)|]*n*<|grad(rho)|**2>*(dVol/drho)  (#/sec)

Here the angle brackets denote the usual differential volume average, i.e.
<f>=integral(dl*2*pi*R*f/grad(rho))/integral(dl*2*pi*R/grad(rho)); the 
denominator in this expression is (dVol/drho).

The VMO input data, however, is a flux surface averaged velocity v_avg 
defined in terms of an equivalent particle flux:

   FLOW = n*v_avg*[Surface_Area]  (#/sec)

where [Surface_Area] is the surface area of the flux surface i.e. 
(2*pi)*integral(dl*R).  The relationship between VMO and the flux surface 
constant is then

  [v/|grad(rho)|] = v_avg*[Surface_Area]/(<|grad(rho)|**2>*(dVol/drho))

Again v_avg is given by the VMO data.

The incremental momentum flux associated with v_avg has an extra 
m*omega*R**2 and surface integrated has form

   MFLOW = (dVol/drho)*n*m*omega*<R**2*|grad(rho)|**2>*[v/|grad(rho)|]

This is all just following Goldston's paper [1], though I made the choice
to input VMO as v_avg, so that the momentum flux driven by it would have
the same relationship as the momentum flux attributed to the convective
radial velocities inferred from particle balance (TRANSP output PRVEL
multigraph contains these velocities, which are also averages, not assumed
to be flux surface constants.

The metrics you need, which are in the TRANSP output, are:

   SURF   [Surface_Area]
   GX2    <|grad(rho)|**2>
   GR2X2  <R**2*|grad(rho)|**2>  (also used in the momentum diffusion term)
   ...and DVOL.

I hope this makes things sufficiently clear.  For future reference, I will
post this message in the TRANSP HELP where it will appear shortly.

         ---Doug

[1] R.J. Goldston, in Basic Physical Processes of Toroidal Fusion
Plasmas (Proc. Course and Workshop Varenna, 1985) EUR-10418-EN, 
(CEC, Brussels, 1986) Vol. 1, p. 165.


5 Time_Varying_Model
Different time intervals can use different models for chi(phi).
To do this, set

  TVPHMODA = [ascending sequence of times, max 8]
  NVPHMODA = [sequence of valid model codes]
  XVPHMODA = [sequence of anomalous multipliers].

The valid NVPHMODA values are as listed in the neighbouring topic
on Vphi prediction.  A zero value denotes analysis of given rotation
data.

NVPHMOD applies from time TINIT to time TVPHMODA(1).
NVPHMODA(j) applies from time TVPHMODA(j) to time TVPHMODA(j+1).
XKFVPH  applies from time TINIT to time TVPHMODA(1).
XVPHMODA(j) applies from time TVPHMODA(j) to time TVPHMODA(j+1)
  and controls the anomalous chi(phi) multiplier in that time
  interval.

If a transition from prediction to analysis occurs in the course
of the simulation, e.g. NVPHMODA(j-1).gt.0 but NVPHMODA(j).eq.0, 
then, a transition time is needed to move continuously from the
last predicted rotation profile to the data profile.  This time,
in seconds, is specified in namelist control DTOMSAVE.

Example:

  NVPHMOD=0
  TVPHMODA=3.0,4.0,5.0
  NVPHMODA=2,1,0
  XVPHMODA=2.0,1.0
  DTOMSAVE=0.025

interpretation:

  analysis, from TINIT to 3.0 seconds, using rotation input data.
  NVPHMOD=2, multiplier=2.0, from 3.0 to 4.0 seconds
    [chi(phi)=2.0*chi(i)]
  NVPHMOD=1, multiplier=1.0, from 4.0 to 5.0 seconds
    [use chi(phi) from Ufile input data]
  analysis, from 5.0 seconds to FTIME.
    take DTOMSAVE=0.025 seconds to transition from the last
    predicted rotation profile at 5.0 seconds to the rotation
    input data.

  note that XKFVPH and XVPHMODA(3) were not specified.  They are
  not needed in rotation analysis mode (also, their default values
  are 1.0).
5 Anomalous_torque
An anomalous torque density profile can be introduced into the
momentum balance, using the TQI profile Ufile input channel.

This is a torque density in the usual TRANSP units:  Nt-M/cm3 --
i.e. the same units as the code's torque density outputs.

5 RPLOT_outputs
The following summarizes momentum balance outputs from TRANSP.

For the ions there is a parallel set of plots ROBAL/ROBALI that
show the balance and sources in units of power (torque -> omega*torque,
i.e. work done).

The MOBALI multigraph shows the source torques from NBI: collisions, 
JxB, thermalization; the sum is TQIN.  MOBAL balances TQIN against 
losses and d/dt[momentum]; M0NET is counted as one of the losses.

Details on the neutrals (usually a small term):

M0NET is cast as a loss term (hence the - sign in MOBAL).  It is 

  [beam halo CX loss + multi-generation thermal neutral CX loss (TQCX) - 
   recapture ionization].

It includes contributions due to both the edge sources and the halo 
source.

The TQ0BA (neutral momentum balance) shows these terms separately, but 
with the signs reversed (ions' loss is neutrals' gain).  In this multigraph
the term TQVLMT, "neutral vol sce torque" is the beam halo CX neutral 
source (thermal ion sink) term.

4 PTRANSP
[F.Halpern, May 2008].
[Updated DMC Mar 2009].

This document section is intended to provide a concise guide to 
the use of the predictive version of the TRANSP code, known as
PTRANSP.

The PTRANSP controls have been significantly modified in 2009.

PTRANSP controls address the following choices:

  -- which PTRANSP solver to use;
  -- which predictive transport equations to solve
     (and conversely which quantities to treat as input);
  -- which predictive transport model to use, over which plasma
     regions, and with what options.

5 PTRANSP_solver_selection

The namelist variable   lpredictive_mode   selects PTRANSP mode and
the solver framework:

  lpredictive_mode = 0 -- traditional TRANSP analysis mode (default).
                          Generally, temperatures and densities and
                          toroidal angular velocity are set by input
                          data.  Legacy "separation of variables"
                          predictive calculations for {Te,Ti,Pphi}
                          can still be used, but with limited 
                          options for predictive transport models.
  lpredictive_mode = 1 -- Plasma State "small step" solution, using
                          state objects {ps_ta,ps_tb} to span a
                          single solver step [ta,tb].  If the solver
                          needs to shorten the timestep it returns
                          control to the PTRANSP "trcom" kernel for
                          data updates.  
  lpredictive_mode = 2 -- Plasma State "large step" solution,
                          using state objects {ps_tg1,ps_tg2}
                          synchronized to the MHD equilibrium time
                          step (tg1,tg2).  The large step solver
                          contains its own sub-cycling timestep
                          control and advance algorithm.  This
                          environment is envision for the ONETWO
                          GCNM-P solvers by Dr. Holger St. John.
                          (DMC March 2009).
  lpredictive_mode = 10-- "trcom" kernel based PTRANSP solvers
                          by Dr. Glenn Bateman: {Te,Ti,PPhi} --
                          plan is to retire this in favor of Plasma
                          State based option, lpredictive_mode=1.

5 Updatability_in_time
Taking advantage of a new TRANSP capability, PTRANSP model controls
can be updated at select times over the course of a time dependent 
simulation.

In other words, a namelist update can be provided to request that
different quantities be predicted and/or different transport models
be applied, possibly with different options, over different time 
regions within a single simulation.

Not all controls are updatable.  For example, only a single solver
can be used within a given PTRANSP simulation, i.e. LPREDICTIVE_MODE
cannot be changed in the course of a run.

6 Finding_updatable_quantities

In the TRANSP source code, codesys/source/freeshare/port.spec defines
the TRANSP namelist and other internal communications variables.  Those
namelist quantities that include a tilda ("~") in their type specification
are modifiable through an update namelist.  For example the integer:

port.spec: ~I  0  LPREDICT_TE = 1  ! =1 to predict TE temperature profile

this is an updatable control.

5 PTRANSP_equation_selection
The following controls have values of either 1 or 0.  1 means, use the
predictive transport model to advance the quantity; 0 means, either use
input data (at the start of a run), or, scale previous predicted results
proportionally to changes in the boundary condition (if a previous use
of predictive model is rescinded with a namelist update).

These controls only have meaning if a PTRANSP solver is active:

  lpredict_Te (default 1) -- predict Te
  lpredict_Ti (default 1) -- predict Ti
  lpredict_Pphi (default 1) -- predict Pphi and angular velocity
  lpredict_ne (default 0) -- predict electron density
  lpredict_nmain (default 0)-- predict main plasma ion densities
  lpredict_nimp (default 0) -- predict impurity ion densities

Only certain combinations are supported (which combinations are specified
in source/tr_util/ptlogic.f90 which will be updated as new capabilities 
are added).

Re: density prediction:

Generally, if lpredict_nmain=1 or lpredict_nimp=1, lpredict_ne=1 is
implied.  If lpredict_nmain=1 and lpredict_nimp=0, Zeff input data is
used; Zeff and quasineutrality are used to infer impurity and electron
densities.  If lpredict_nmain=lpredict_nimp=1, Zeff is output, both the
main plasma and impurities are evolved independently, and electron 
density is inferred by quasineutrality.  If lpredict_ne=1 while 
lpredict_nmain=lpredict_nimp=0, Zeff data is used with quasi-
neutrality to infer the resulting impurity and summed main ion 
densities; the traditional TRANSP ad hoc mixing model will be 
employed to predict the main ion species mixture.  The combination
{lpredict_nmain=0, lpredict_nimp=1} will not be supported, initially.

The above controls apply over all transport regions up to specified
boundary locations which can vary depending on the quantity predicted.

5 PTRANSP_transport_region_boundaries
Unlike traditional TRANSP, PTRANSP allows multiple predictive transport
models to be combined.  The controls used for PTRANSP are different than
the controls that were used in tradional TRANSP, as is necessary to
support this capability.

In PTRANSP, the core plasma is divided into three regions, within
each of which a different combination of transport models may be 
selected (here xi is the radial toroidal flux coordinate, 
xi=sqrt(Phi_tor/Phi_tor_bdy)):

  -- axial region (can have null extent): xi range 0 to XIMIN_CONF;
  -- confinement region: xi range XIMIN_CONF to min(XIMAX_CONF,X*BOUND);
  -- near-edge region (can have null extent): xi range XIMAX_CONF to
     to X*BOUND.

The (updatable) namelist controls XIMIN_CONF and XIMAX_CONF define the 
boundaries of these regions; default values are XIMIN_CONF=0.0 and 
XIMAX_CONF=1.0 (which would leave the axial and near-edge regions with
null extent).

The following controls are superseded by {XIMIN_CONF,XIMAX_CONF}: these
are IGNORED in PTRANSP runs: 
  {XIMINGLF,XIMINMMM,XIMAXGLF,XIMAXMMM,XIMAXGKF}.

{XIMIN_CONF,XIMAX_CONF} define the above listed three regions of 
application of predictive models; however, all regions are bounded by 
the "boundary region", within which either input data or a predictive 
Pedestal Model determine temperatures, densities, and plasma rotation 
rates.  The boundary location can differ according to predictive 
quantity, as follows:

  XIBOUND (default 1.0) -- boundary location for Te and Ti prediction;
  XPHIBOUND (default 1.0) -- boundary location for Pphi prediction;
  XNBOUND (default 1.0) -- boundary location for density prediction.

Collectively these are referred to as X*BOUND, above; these can limit
the extent of either the confinement region or the near-edge region.

It is possible for the axial and near-edge regions to have null extent,
in which case controls on transport in these regions would have no 
effect.

5 Transport_model_selection

WARNING WARNING WARNING -- this section to be rewritten, the control
structures and names are being redesigned...

PTRANSP uses logical switches with names of the form L_<model>_<region>
to select a model for use within a specified region.

Examples:

model              region....................................
                   axial           confinement    near-edge
Chang-Hinton NC    L_CHNEO_AXIAL   L_CHNEO_CONF   L_CHNEO_EDGE   
Neo-Alcator        L_ALC_AXIAL     L_ALC_CONF     L_ALC_EDGE

All switches default to .FALSE.; multiple switches can be active within
a region, in which case the transport coefficients of the selected models
are used additively.  If certain models are deemed incompatible, this will
be caught and reported when PTRANSP is started-- see restrictions.

Note that some of the named transport models calculate transport 
coefficients only for a subset of transported quantities.

[tentative table DMC Mar 2009]
model     Te      Ti      Pphi    ni      nx      ne

CHNEO     x       x       x
NCLASS    x       x       x       x       x       x
GLF23     x       x       x       x       x       x
MMM95     x       x       x       x       x       x
MMM07     x       x       x       x       x       x
TGLF      x       x       x       x       x       x
ALC       x       x       x       x       x       x

For each transported quantity under each model, and in each region in
which the model is available, anomalous multiplier controls are provided.
All have default values of 1.0; names are of the form

   X<quantity>_<model>_<region>

Here <quantity> is reduced to a two letter code:

   quantity                2-letter code
                               (lpredict_<quantity> suffix if different)
   Ion temperature  --     Ti
   Electron temperature -- Te
   Angular momentum --     Pp  ("Pphi")
   Main ion densities --   ni  ("nmain")
   Impurity densities --   nx  ("nimp")
   Electron density   --   ne

All such quantities can be modified by namelist update.  Examples:

   XTi_CHNEO_AXIAL  --  multiplier on Chang-Hinton chi(i), in axial region

   XPp_GLF23_CONF  --  multiplier on GLF23 predicted Pphi transport,   
                                                    in confinement region

For more examples: see "Combination controls" subtopic.

The anomalous multipliers allow different transport models to be in 
effect for different transported quantities.

6 Combination_controls
These controls, offerred in early PTRANSP versions, remain available:

NLNEOCL=.TRUE. => L_CHNEO_AXIAL = L_CHNEO_EDGE = .TRUE.
CONINEO=<value> => XTi_CHNEO_AXIAL = XTI_CHNEO_EDGE = CONINEO
CONENEO=<value> => XTe_CHNEO_AXIAL = XTE_CHNEO_EDGE = CONENEO
CONPNEO=<value> => XPp_CHNEO_AXIAL = XPP_CHNEO_EDGE = CONPNEO

NLALCAT=.TRUE. => L_ALC_AXIAL = L_ALC_EDGE = .TRUE.
CONIALC=<value> => XTi_ALC_AXIAL = XTi_ALC_EDGE = CONIALC/1.0d18
CONEALC=<value> => XTe_ALC_AXIAL = XTe_ALC_EDGE = CONEALC/1.0d18
CONPALC=<value> => XPp_ALC_AXIAL = XPp_ALC_EDGE = CONPALC/1.0d18
CONNALC=<value> => Xni_ALC_AXIAL = Xni_ALC_EDGE = CONNALC/1.0d18
                => Xnx_ALC_AXIAL = Xnx_ALC_EDGE = CONNALC/1.0d18
                => Xne_ALC_AXIAL = Xne_ALC_EDGE = CONNALC/1.0d18

NLPALEO=.TRUE. => L_PALEO_AXIAL=L_PALEO_CONF=L_PALEO_EDGE = .TRUE.
           (electron energy transport only)
           => XTe_PALEO_AXIAL=XTe_PALEO_CONF=XTe_PALEO_EDGE = 1.0
           => XTi_PALEO_AXIAL=XTi_PALEO_CONF=XTi_PALEO_EDGE = 0.0
           => XPp_PALEO_AXIAL=XPp_PALEO_CONF=XPp_PALEO_EDGE = 0.0
           => Xni_PALEO_AXIAL=Xni_PALEO_CONF=Xni_PALEO_EDGE = 0.0
           => Xnx_PALEO_AXIAL=Xnx_PALEO_CONF=Xnx_PALEO_EDGE = 0.0
           => Xne_PALEO_AXIAL=Xne_PALEO_CONF=Xne_PALEO_EDGE = 0.0


However these switches now default to .FALSE.; for reference to
source code see source/tr_util/ptlogic.f90.

6 Restrictions
[not defined as of March 2009 -- DMC]
[It might be necessary e.g. to permit TGLF or GLF23 but not both at once].

Early versions of PTRANSP will not support all possible combinations.
Namelist and namelist update input checks will attempt to prevent use
of unsupported combinations.

5 Coupled_Solver_Settings

The following controls apply when lpredictive_mode = 1:

The TSC coupled Te/Ti/... quasi-Newton solver runs by default with
these PTRANSP modes.

This solver is recommended for stiff models such as GLF23.
The available options are:

NEWTON_ITERATES = 3   ! Number of Newton interations
THETA_IMPLICIT  = 1.0 ! Implicitness parameter in time differencing

The quasi-Newton portion of the solver is turned off with the namelist
option

NEWTON_ITERATES = 0

When the quasi-Newton iteration is turned off,
the stiffness of the transport models will cause numerical artifacts 
in the temperature profiles. This effect can be mitigated by
mixing the diffusion coefficients with the relaxation factor
XRELFAC. With NEWTON_ITERATES=0, it is recommended that XRELFAC=0.1.

The Newton's method solver is recommended for GLF23 and MMM95. Due to
numerical issues in the implementation of the Weiland model,
NEWTON_ITERATES=0, XRELFAC=0.1 is recommended for use with 
the Weiland model until further notice.

5 Transport_model_options
See appropriate subtopic...
6 GLF23 options

Of the three confinement region models normally used in PTRANSP, GLF23 
is by far the one with the most knobs. The complete documentation for 
GLF23 can be found at the GLF23 NTCC page (w3.pppl.gov/ntcc)

The original GLF23 setting can be found at the NTCC page. Here,
the settings listed correspond to the "retuned" version of GLF23,
with gradients specified externally so that the Newton's method
works correctly.

L_GLF23_CONF = .TRUE.

LIGLF    = 1   ! =0 (default) original normalization, =1 for renormed model
LIGRAD   = 1   ! =0 Use GLF23 gradients, =1 (default) use TRANSP gradients
LDENGRAD = 2   ! =2 (default) simple dilution, =3 full dilution
LX_ALPHA = 0.0 ! =0.0 (default), real coefficient for alpha stabilization
LTPORT(5)= 1,1,1,1,0 ! to invoke D,Te,Ti,Vphi,Vtht transport coefficients
LNROOT   = 8   ! =8 (default), use =12 for full impurity dynamics
ALPHA_E  = 1.0 ! =0.0 (default), w_ExB shear multiplier (see section on ExB shear)
LROTSTAB = 1   ! =0 (default) TRANSP ExB shear rate, =1 internally computed shear rate
LBT_FLAG = 1   ! =0 (default), =1 (recommended) use effective B_T

XIMIN_CONF = 0.0 ! Inner radial boundary for GLF23 model 
XIMAX_CONF = 1.0 ! Outer radial boundary for GLF23 model

Sometimes, GLF23 causes Te to peak on axis. This can be remedied using 
XIMIN_CONF=0.1 along with:

NLNEOCL=.T      ! .T for for Chi=CONINEO*Chang-Hinton (default=.F)
CONINEO=5.0     ! coefic of Chang-Hinton (default=1.0)
CONENEO=5.0     ! coefic of Chang-Hinton (default=1.0)

6 MMM95 options

There are few options for the MMM95 models, which also apply to the
Weiland model.

NLEXB    : =FALSE (default) flag for ExB flow shear stabilization
FACEXB   : =1.0 (default) Real multiplier for ExB shear
NLEXBMOD : =0 (default) for Indireshkumar's routine, 1 for Halpern's routine
XIMIN_CONF: =0.0 (default) Inner radial boundary for MMM95 model 
XIMAX_CONF: =0.0 (default) Outer radial boundary for MMM95 model

6 Weiland model options

The ExB shear multiplier and other options are handled using the
same switches that MMM95 uses.

XIMAX_CONF=0.8 is recommended for the Weiland mode.

The following setting must be used when momentum transport is being
predicted:

CMMM07(1)=0.0

To turn the momentum transport pinches off, which are not implemented 
correctly yet.

6 ExB shear settings

TRANSP computes ExB shear rates in two different subroutines,
which can be accessed using NLEXBMOD=0 (default, Indireshkumar
routine) or NLEXBMOD=1 (Halpern routine). The scaling factor
for the ExB shear rates is FACEXB (1.0 is default).
MMM95 and the Weiland model can only use TRANSP computed rates.

GLF23 can use either TRANSP computed rates or internally computed
rates. GLF23 computes the flux surface average of the ExB shear
rates, which is larger than the value at the outboard edge computed
by TRANSP. GLF23 can also use the TRANSP shear rates. These are
some examples of usage:

!GLF23 with internal ExB shear rates
ALPHA_E=1.0  !GLF23 multiplier for ExB shear
LROTSTAB=1   !Use internal GLF23 ExB shear rates

!GLF23 with TRANSP ExB shear rates
ALPHA_E=1.0  !Note GLF23 multiplier still applies
LROTSTAB=0   !Use TRANSP ExB shear rates
NLEXB=T      !Turn on TRANSP ExB shear computation
NLEXBMOD=0   !To use Indireshkumar's routine (default) or =1 for Halpern's routine
FACEXB=1.0   !TRANSP multiplier for ExB shear

!MMM95 or Weiland model with TRANSP ExB shear rates
NLEXB=T      !Turn on TRANSP ExB shear computation
NLEXBMOD=0   !To use Indireshkumar's routine (default) or =1 for Halpern's routine
FACEXB=1.0   !TRANSP multiplier for ExB shear

5 Boundary condition for temperature prediction

Several options are available for use as a boundary condition
to the temperature profiles. The radial location of the 
boundary must be set through the namelist variable XIBOUND
(for temperature prediction), XPHIBOUND (for momentum prediction),
and XNBOUND (for density prediction).  These quantities mean that
either input data or a Pedestal Model must provide the corresponding
data for XI grid zones that are at or beyond the X*BOUND values.

The boundary conditions are covered in detail in the help section 
dedicated to the analysis mode of the code.

PTRANSP can make use of experimental data or use of the PEDESTAL
module by invoking the correct mode option for the namelist 
variables MODEEDG (Te boundary condition) and MODIEDG (Ti b.c.).
The most commonly used modes are

MOD*EDG = 3    ! Use experimental Te data for XI > XIBOUND
MOD*EDG = 4    ! Use experimental Ti data for XI > XIBOUND
MOD*EDG = 5    ! Use predictive PEDESTAL module or namelist controls

Note that the Te/Ti boundary condition settings are independent
of each other. 

Details of the PEDESTAL controls are described in the section on
boundary conditions to the ion power balance equation.

5 Boundary condition (Pphi equation)

The only option available is to make use of experimental data
for the edge. Thus, a VP2 or OMG ufile must be read in. The
radial location of the boundary is set with the variable 
XPHIBOUND. When GLF23 or the Weiland model are used, the value
XPHIBOUND=0.8 is recommended.

5 Equilibrium

There are several equilibrium packages available. They can be invoked
with the LEVGEO namelist option, and work in exactly the same way
in PTRANSP as in the analysis mode of the code.

5 Poloidal diffusion equation

It is recommended that the poloidal diffusion equation be solved self
consistently. The recommended settings are 

NLMDIF=T      !Solve poloidal diffusion equation
NLPCUR=T      !Total plasma current vs. time is input bdy. cond.
NLVSUR=F      !Surface voltage is free to float up and down
NLBOOT=T      !Use bootstrap currents
NEFLD=7       !Initialize the q profile from experimental data

[remove NQMODA and TQMODA references in your namelist, unless you
intend to switch back and forth between using the poloidal field
diffusion equation and a data source for q(x,t)].

Other options are available for the initialization of q profiles.

4 Fast_Ion_Species
[DMC Feb 1992, updated 2010] The TRANSP Monte Carlo code may 
simultaneously model any number of fast ion species per run.  Fast ion 
species can be either neutral beam species or fusion product species.

Usually, fast ion species in TRANSP require a corresponding thermal
ion species to be present.  This rule is waived for fusion product
fast ion species and for heavy neutral beam species.

The following gives the list of supported fast ion species:

Fusion Products:
  He4 (alpha ions) produced by DT and various other fusion reactions
  T (tritons) produced by DD fusion
  He3 produced by DD fusion
  (modeling of fusion product protons not currently available)

  note that if you model D->D neutral heating and follow the T and
  He3 fusion product ions, you have 3 fast ion species in the model,
  D (beams) and T and He3 (fusion products).  The run must include
  a thermal D population, but thermal T or He3 are not required.

Neutral Beams:
  Hydrogen isotopes H, D, T are supported, as before
  Helium isotopes He3 and He4 are supported now (1992).
    If the ib'th beam is He3, for example, set
      ABEAMA(ib)=3.0
      XZBEAMA(ib)=2.0
  Heavy neutral beams (Neon, Argon, Krypton, Xenon) are now supported:
      Neon:      A,Z = 20.2, 10
      Argon:     A,Z = 39.0, 18
      Krypton:   A,Z = 83.7, 36
      Xenon:     A,Z = 131.3, 54
    A and Z are specified via the ABEAMA and XZBEAMA controls on a 
    beam by beam basis.  Use Monte Carlo control NPTCLH to set a
    lower statistical control for heavy beam species.  For numerical
    and physical reasons the modeling of these species can be slowww...
4 LOWER_HYBRID_(LSC)
(2/5/93 tbt)
The Lower Hybrid Code (LSC) was installed in TRANSP in 1992. 

LSC ... lower hybrid simulation code ... was written by
D.W. Ignat and E.J. Valeo to do multiple ray tracing in general
non-circular axisymmetric plasmas specified by a numerical
equilibrium, solve at each of several flux surfaces
a simple one-dimensional (in velocity)
Fokker Planck equation for the quasilinear evolution of the
electron distribution function, and provide the rf power and
rf-driven current deposited to the calling program.
An important element of the approach is to use the
electric field sensitive response functions of Karney and Fisch
to account for the complexities of driving current in the presence
of constant electric field.

Some References:
       D. W. Ignat, Phys. Fluids, <24>, 1110 (81);
       E. J. Valeo and D. C. Eder, J. Comp. Physics, <69>, 341 (87).
       C. F. F. Karney and N. J. Fisch, Phys. Fluids <29>, 180 (86).

DMC Feb. 1997:  there is a new lower hybrid heating and current
drive profile input option; see the "generic" subtopic.
5 General_Namelist_Controls
-->new 11 Feb 1997 (dmc):  The lower hybrid electron heating and
driven current profiles may now be input to TRANSP and used by
setting the NLLHUDAT switch.  See the subtopic...

The following Namelist parameters are used in controlling the
interface with LSC.

VARIABLE   Sample      Explanation
           Values

NLLH	   T           Turns on lower hybrid (LSC) code.
DTLH       .005        Frequency of ray tracing within LSC calculation
		       in seconds. Note: ray tracing is also done every
                       time a restart file is read or written.

NantLH     1           number of LH antennas

  ! these controls can be used if there is just one antenna:
TotPwrLH   1.E6        Total power input to LSC in watts.
TLHOn      0.5         Start time of LSC heating in seconds.
TLHOff     1.          End   time of LSC heating in seconds.

NLLHTFIX   T           set on/off time from Ufile input data (if any)
                       no effect if power set from namelist.
 if NLLHTFIX is true:
     PLHTFIX  -- threshold power (watts if positive, -fraction
                 if negative) to define on/off times from input
                 power vs. time; default is -0.05, i.e. threshold
                 is 5% of the maximum power.
     DTLHTFIX -- time to back off from threshold power times,
                 looking for actual zeroes in the input power.
                 default:  0.01 seconds.

use TRDAT input file PRELHP/EXTLHP to set the Lower Hybrid antenna
power as a function of time from Ufile data.
6 Profile_Input
[updated Feb 2006 (dmc)]
The Lower Hybrid heating and current drive profiles may now be
specified by Ufile input.  To do this, set:

  NLLHUDAT=.TRUE.

in the TRANSP namelist, and in the TRDAT namelist set

  PRELHJ/EXTLHJ to specify the current drive profile input
    Ufile (amps/cm2), and

  PRELHE/EXTLHE to specify the electron heating profile input
    Ufile (watts/cm3).

Optionally the data can be renormalized using scalar f(t) input data:

  PREPLH/EXTPLH -- total LH electron heating vs. time, WATTS
  PREILH/EXTILH -- total LH current vs. time, AMPS

The usual TRANSP/TRDAT controls apply, e.g. set NRILHJ and NRILHE
to specify the type of spatial coordinate supplied in the Ufile.
NRILHJ=NRILHE=6 can be used if the spatial coordinate given is
normalized poloidal flux.

ON and OFF times:

For backwards compatibility reasons (and unlike other similar power
data input options in TRANSP) the default behavior is that the ON and
OFF times **need to be specified** in the namelist:

   TLHON = time the LH heating and current drive start
   TLHOFF= time the LH heating and current drive stop.

However, it is possible to request that these on/off times be inferred
from the input data.  To get this behavior, set:

   NLLHU_TFIX = .TRUE.

In this mode, the Lower Hybrid on/off times TLHON and TLHOFF are taken
from the POWER profile (LHE data).  It is assumed without checking that
the same on and off times should apply to the other related input signals 
LHJ, PLH, and ILH.

The Lower Hybrid predictive models are not used, and
NLJLH & NLLH should be false in the namelist.

If the LHE and LHJ Ufiles are given, NLLHUDAT=.FALSE., and
a predictive model is used, the Ufile data will be passed thru
to RPLOT for comparison.

5 Brambilla_Namelist_Controls
Some namelist variables are only necessary when the Brambilla
calculation is done. The determination of this is done with NDoBram.

NDoBram     1          1= do a Brambilla calculation with JEStevens code

If NDoBram = 1 then

  NGrpsLH    3           Number of couplers.
   ! NOTE: if NANTLH.gt.1 this must be 1; in multi-antenna simulation
   ! there can be only one LSC coupler per antenna;
   ! in this case PhasLHAN(j) gives phasing to the j'th antenna
   ! and powersLH(j) = POWRLHA_USE(j)/TOTPOWRLH

  phaseDLH   90.         array of size NGrpsLH giving phase change
                        in degrees from wave guide to wave guide for
                        each coupler. 
  powersLH   1.0         array of size NGrpsLH giving relative power in
                        each coupler.
  NcuplrLH   1	         array of size NGrpsLH giving each coupler's code.
                        The numerical specifications for each type of
                        coupler are internal to LSC. If a new coupler
                        is to be defined, the user should see David
                        Ignat to decide specifications.

		       Code 1 => 'PBXMFAST' => original,faster, coupler.
		       Code 2 => 'PBXMSLOW' => FY 93 installed slower
                                               coupler.
		       Code 3 => 'TOKDEVAR" => Montreal coupler.
                                         Phase is the Cadarache usage.
		       Code 4 => 'TORSUPRA" => French coupler.

If NDoBram = 0 then

  NGrpsLH    3           number of groups for spectrum: 
  powersLH   1.0         array of size NGrpsLH giving relative power in
                        Gaussians.
  centerLH   4.0         array of size NGrpsLH giving npar at 
			center of Gaussian
  widthsLH   1.0         array of size NGrpsLH giving npar 
                        width of Gaussian.
  parmaxLH   5.5         maximum npar if 'modeled spectrum' 
  parminLH   2.5         minimum npar if 'modeled spectrum' 

5 Debugging_Namelist_Controls
The following Namelist controls can be used by the maintance
programmer for debugging the LSC portion of TRANSP.

VARIABLE   Default     Explanation

NPlFlgLH    25*0       Array (Dim=25) of Plotting flags
NPrFlgLH    25*0       Array (Dim=25) of Printing flags
NdiaGLH     0          Array (Dim=50) of QL ramp indices
                        at which graphs are made.
NDoPasLH    0          1= allows code to pause at certain points
NDoScrLH    0          1= controls some screen output
NDoComLH    0          1= controls some screen output
NDoDBgLH    0          1= controls some debuging/diagnostic outpu

5 BIN_LSC_Namelist
The following LSC namelist variables are related to describing
velocity bins.

nvLH       199         number of velocity bins (must be odd number).
StpRngLH   4.0         small bins near v=0 are StpRngLH 
		       smaller than large bins
StpRngLH..             near v=1 (v=c);  active if vgrtype = 3
NgtypeLH    1          velocity grid type code: 
		        ( 1=linear; 2=Obsolete; 3=exponential)
nsmooLH    9           num of velocity bins for smoothing D_ql
nsmwLH     3           characteristic width of function 
	               covering nsmoo v bins

5 TRANSP_Namelist_For_LSC
The following is the complete set of TRANSP namelist variables 
passed into LSC common. 

                       LSC VARIABLES for INPUT
                            January 1993

VARIABLE   Default     Explanation

nfreqLH    100         steps between preparing ray plot in 3d picture;
nstepLH    500         maximum steps in following each ray
npsiLH     10          number of psi shells internal to LSC 
                        for power/current deposition
nraysLH    10          number of rays
nGrpsLH    3           number of groups for spectrum: 
		       number of couplers if NDoBram=1
nzonesLH   100         number of shell crossings kept track of
nvLH       199         number of velocity bins (must be odd number).
StpRngLH   4.0         small bins near v=0 are StpRngLH 
		       smaller than large bins
StpRngLH..             near v=1 (v=c);  active if vgrtype = 3
NgtypeLH    1          velocity grid type code: 
		        ( 1=linear; 2=Obsolete; 3=exponential)
fghzLH..   4.6         frequency of LSC power in GHz -- now an array
HLH        .005        ray step size in meters
parmaxLH   5.5         max npar if 'modeled spectrum' ... NDoBram = 0
parminLH   2.5         min npar if 'modeled spectrum' ... NDoBram = 0
centerLH   4.0         array of size NGrpsLH giving npar at 
			center of Gaussian
centerLH..              if NDoBram=0
widthsLH   1.0         array of size NGrpsLH giving npar 
                        width of Gaussian
widthsLH..             if NDoBram=0
NcuplrLH   1	       array of size NGrpsLH giving coupler code.
		       Code 1 => 'PBXMFAST' => original,faster coupler.
		       Code 2 => 'PBXMSLOW' => FY93 installed slower
                                               coupler.
		       Code 3 => 'TOKDEVAR" => Montreal coupler phase
                                            in the Cadarache usage.
		       Code 4 => 'TORSUPRA" => French coupler.
phaseDLH   90.         array of size NGrpsLH giving phase on coupler
                        if NDoBram=1
powersLH   1.0         array of size NGrpsLH giving relative power in
                        (Gaussians/couplers) if NDoBram=(0/1)
nsliceLH   301         num of npar slices used in Bram calculation
nsmooLH    9           num of velocity bins for smoothing D_ql
nsmwLH     3           characteristic width of function 
	               covering nsmoo v bins
WgtItrLH   .20         under-relaxation weight in calculating f_e
NPlFlgLH               Array (Dim=25) of Plotting flags
NPrFlgLH               Array (Dim=25) of Printing flags
NDoPasLH    0          1= allows code to pause at certain points
NDoScrLH    0          1= controls some screen output
NDoComLH    0          1= controls some screen output
NDoDBgLH    0          1= controls some debuging/diagnostic output
NDoBram     1          1= do a Brambilla calculation with JEStevens code
NDoGrzLH    0          1= do f_e(v,psi) D_ql(v,psi) graphs 
		          asked by Giruzzi
NDoEVsLH    0          1= use EValeo smoothing method for Jrf; 
			  shouldnt matter
NdiaGLH     0          array (Dim=50) of QL ramp indices
                        at which graphs are made.
nRampULH   10          num of ramp up cycles in quasilinear 
			(QL) calculation
nFlatLH    5           the last nFlat cycles are at the final power
nRampOLH   6           num ramp cycles if starting from the old f_e
NRemFeLH   0           1= ramp from the old f_e;  NOT CERTIFIED OK

5 LSC_Internal_namelist
The following are LSC internal names used in LSC common and are related
to TRANSP Namelist variables. This information is only valuable to a
maintenance programmer.

                       LSC VARIABLES for INPUT
                            January 1993

VARIABLE   Default     Explanation

nfreq      100         steps between preparing ray plot in 3d picture;
nstep      500         max steps in following each ray
npsi       10          num of psi shells for power/current deposition
nrays      10          num of rays
nGrps      3           num of groups for spectrum: 
		       num of couplers if DoBram=1
nzones     100         num of shell crossings kept track of
nv         199         num of velocity bins
StpRange   4.0         small bins near v=0 are StpRangs 
		       smaller than large bins
StpRange..             near v=1 (v=c);  active if vgrtype = 3
vgrtype    1           velocity grid type: 
		        ( 1=linear;2=Obsolete;3=exponential
fghz       4.6         frequency in ghz
HstpLH     .005        ray step size in meters
nparmax    5.5         max npar if 'modeled spectrum' ... DoBram = 0
nparmin    2.5         min npar if 'modeled spectrum' ... DoBram = 0
thet0      0.0         poloidal position of coupler; 0--> normal;  
			NOT USED
centers    4.0         array of size nGrps giving npar at 
			center of Gaussian
centers..              if DoBram=0
widths     1.0         array of size nGrps giving npar width of Gaussian
widths..               if DoBram=0
couplers   'PBXMFAST'  array of size nGrps giving coupler type
phaseDeg   90.         array of size nGrps giving phase on coupler
phaseDeg..             if DoBram=1
powers     1.0         array of size nGrps giving relative power in
powers..               (Gaussians/couplers) if DoBram=(0/1)
nslices    301         num of npar slices used in Bram calculation
nsmoo      9           num of velocity bins for smoothing D_ql
nsmw       3           characteristic width of function 
	               covering nsmoo v bins
WeghtItr   .20         under-relaxation weight in calculating f_e
PlFlg                  Plotting flags
PrFlg                  Printing flags
DoRFDa DoRFHe          for debugging Damping/Heating power calc
DoRFHe DoRFHe          Damping=ray picture; Heating=QL picture
DoPaus     0           1= allows code to pause at certain points
DoScrn     0           1= controls some screen output
DoComm     0           1= controls some screen output
DoDeBg     0           1= controls some debuging/diagnostic output
DoBram     1           1= do a Brambilla calculation with JEStevens code
DoTRAN     0           1= TRANSP is in control
DoFish     0           1= construct D_theta of interest 
		          to Fisch alpha theory
DoBern     0           1= look at the end of equilibrium file to see if
DoBern..                  other values of n_e T_e B_o I_p should be used
DoGrzi     0           1= do f_e(v,psi) D_ql(v,psi) graphs 
		          asked by Giruzzi
DoHarv     0           1= write file of ray data for 
			  CQL3D runs by RW Harvey
DoEVsm     0           1= use EValeo smoothing method for Jrf; 
			  shouldnt matter
DoXcam     0           1= construct the X ray pinhole camera image
idiag                  array of QL ramp index at which graphs are made
nRampUp    10          num of ramp up cycles in quasilinear 
			(QL) calculation
nFlat      5           the last nFlat cycles are at the final power
nRampOld   6           num ramp cycles if starting from the old f_e
iRememFe   0           1= ramp from the old f_e;  NOT CERTIFIED OK
NparEnhc   1.00        at each bounce enhance npar by this;
NparEnhc..             indicates sensitivity to details; 
			increases damping
TurnNegs   0           1= make negative spectrum 'ghosts' go positive
JrfEnhc    1.00        enhance Jrf by this factor.  Obsolete
incLabls   0           1= put (messy) contour labels on graphs

5 Multi_Antenna_Simulation
[DMC March 2011] The TRANSP/LSC interface, and LSC internals have been
improved to allow a simulation involving multiple concurrently energized
Lower Hybrid antennas launching waves at different frequencies:

   I   NANTLH          Number of LH antennae in experiment
   RA  POWRLHan(NANTLH)   LH POWER INPUT on each antenna
                             may be overridden by Ufile data
   RA  PHASLHan(NANTLH)   LH phasing in degrees on each antenna
                             may be overridden by Ufile data
   RA  TONLHan(NANTLH)    LH "on" time for each antenna
                             may be overridden by Ufile data
   RA  TOFFLHan(NANTLH)   LH "off" time for each antenna
                             may be overridden by Ufile data

LSC has a notion of number of "groups" or "couplers" which is more or
less synonymous with number of "antennas": NGRPSLH.  For backwards
compatibility, TRANSP allows NGRPSLH>1 **or** NANTLH>1, but not both.
In either mode, FGHZLH(...) is now an array, and so, different 
frequencies can be associated with different groups (1:NGRPSLH) or
with different antennas (1:NANTLH).  If both NANTLH and NGRPSLH are
greater than one, this will be caught by TRANSP namelist error checking.

The use of NGRPSLH is specific to LSC.  It is not likely to be carried
forward to future Lower Hybrid model implementations.

Notes:
  (a) NANTLH=3 is the maximum allowed for use with LSC.  More modern
      Lower Hybrid models may eventually allow more than three antennas.
  (b) The namelist quantity FGHZLH is now an array, allowing a different
      frequency to be set on each antenna.
  (c) If NANTLH>1, NGRPSLH=1 is required.  These LSC controls dimensioned
      by group index are considered to apply to antenna index instead:
         NCUPLRLH, WIDTHSLH, CENTERLH;
      Also, POWERSLH is reset to the relative antenna powers with
      NANTLH>1, so POWERSLH (relative power) in the namelist only has 
      an effect if NANTLH=1 and NGRPSLH>1.
  (d) For backwards compatibility, with NDOBRAM=1:
      If NANTLH=1, PHASEDLH(1:NGRPSLH) gives the coupler phasing;
         to force PHASLHAN(1:NGRPSLH) to be used even with NANTLH=1,
         set PHASEDLH(1) to a large negative value: -1000.0; the test
         in the code is (PHASDLH(1).lt.-999.0).
      If NANTLH>1, PHASLHAN(1:NANTLH) is used; PHASEDLH is overwritten.

5 Output_times
The LSC interface library (lhintrfc) saves data at select intermediate
times for standalone LSC runs which can be done after TRANSP completes.

By default these times are scattered roughly equally between TLHON and
TLHOFF with about 20 time points saved.

To control the times used, set elements of the TIMLSOUT array:

  TIMLSOUT(1) = <1st output time, seconds>
  TIMLSOUT(2) = <2nd output time, seconds>
  TIMLSOUT(3) = <3rd output time, seconds>

     --etc--

or all in one line (for example):

  TIMLSOUT = 0.16, 0.175, 0.200, 0.225, 0.275   ! Times for LSC files

6 Standalone_LSC
A good description (by Alex Pletzer ca. 2000) is in the TRANSP reference
documents (source/doc/new_lsc.doc, ascii text).

To summarize:  a completed LSC TRANSP run should include a saved file

  <runid>LSCINPUT.XML

which the user should copy into an empty working directory.

Then, the TRANSP client software includes a procedure "mkniput4lsc" to 
extract from this concatenated data file the input data for a particular 
saved time:

  mkinput4lsc <runid> <time> [delta_t]

This procedure is interactive in that it allows the user to set plotting
flags for the standalone run.

Then, there are two programs, "lsctest" and "lsctest_dmc", with slightly
different interfaces, that accept the data extracted by "mkinput4lsc".
These extracted files are "jardin.d_<suffix>" and "input.lhh".  The <suffix>
indicates the <runid> and <time> of extraction.  The programs are run and
request the full name of the "jardin.d" file to be used as input.  The
programs produce graphical output that can be converted to post-script and 
viewed e.g. with "ggv".

4 HIGHER_HARMONIC_HEATING_(CURRAY)

CURRAY was installed in Transp in 2003.

Its use in TRANSP is experimental; the code has not been well validated.

CURRAY is a ray tracing code that is used primarily for modeling radio 
frequency heating and current drive in the ICRF and LH frequency regimes 
for tokamaks. This package has its origin in RAYLH/RAYIC, 
a ray code written by Marco Brambilla in the early '80s.

In the early '90s, T.K. Mau (then at UCLA) and S.C. Chiu of 
General Atomics modified the original code considerably to include a 
fast branch to model and predict fast magnetosonic 
wave heating and current drive in experiments (DIII-D) and conceptual 
power plant designs (ARIES). This latest development led to the code 
officially re-named CURRAY to stand for 'current drive modeling with 
ray tracing'. In the mid '90s, a current-drive efficiency calculation 
package based on the adjoint technique and written originally by 
Charles Karney, was added to CURRAY thus greatly extending 
the applicablity of the code to tokamaks of all aspect ratios. 

(For more details about CURRAY, please consult the NTCC modules web page:
w3.pppl.gov/NTCC.) 

Here, we will concentrate on accessing CURRAY from
TRANSP and the associated inputs and outputs. The variables in parentheses
next to TRANSP variables are the original (CURRAY) variables. Please consult
the NTCC documentation on CURRAY module for more information.   

5 TRANSP_NAMELIST_Controlled_Parameters_(Minimal_Set) 
 (The names in parentheses are CURRAY variable names)


nlcurray          .F              Invokes curray if .T


tcuron            0.0             Time when higher harmonic power is turned
                                  on (Must be set) 

tcuroff           0.0             Time when higher harmonic power
                                  is turned off (Must be set) 

ptotcur (ptot0)   0.0             Total wave-power in MW (spectral power will
                                  be re-normalized so that total power is this value).

cfreqcy (freqcy)  0.0             Wave frequency (Hz) 

cheight(heigth)   100.0           Antenna height or poloidal extent (cm)


nthin (nthin)     1               Number of poloidal ray starting locations for each
                                  toroidal refractive index

nnkpar(nnkpar)    1               Number of Nparallel's in each toroidal bin 
                                  (array)

nzinf (anzinf)    0.0             Lower limit of toroidal refractive index in j-th bin 
                                  (array)

anzsup (anzsup)   0.0             Upper limit of toroidal refractive index in j-th bin
                                  (array)

nnkpol (nnkpol)   1               Number of n-poloidal's in j-th bin
                                  (array)

anpinf (anpinf)   0.0             Lower limit of poloidal refractive index
                                  (array)

anpsup (anpsup)   0.0             Upper limit of poloidal refractive in j-th bin

                                  [note: The total number of rays is
                                  sum(1 to nspect) of nnkpar(j)*nnkpol(j)*nthin ]

thgril(thgril)   1.0              Approximate central location of antenna in degrees
                                  w.r.t. outer equatorial plane
                                  (do not set equal to or too close to 0)

5 Output_from_CURRAY

Rplot output from CURRAY can be accessed via the following variables:

pehh        ------  Profile output of power deposition to electrons

pihh        ------  Profile output of power deposition to ions 

hhcur       ------  Driven Current

pfihh       ------  Power deposited to fast ions if nfastcr=1 (see below) 

ptihh       ------  Power deposited to thermal ions if nfastcr=1 (see below) 

In addition, the multigraph CRIHEAT shows powe deposited to fast ions,
thermal ions, and ions (all). The multigraphs EEHEAT, IEHEAT and PCURS include
power deposition and current drive due to heigher harmonic heating


5 Additional_namelist_parameters_(CURRAY) 


  nlgraph (igraph)     .T      Graphics output control
                               (.T graphics output)

  nldrive (idrive)     .T      CD calculation (.T);
                               No CD calculation (.F)

  nlmodcd (modcd)      .F      Flag for CD efficiency model;
                               .F -- Ehst/Karney

  pkexpnt (pkexpnt)    0.001   Parameter for adjusting the 
                               radial step size for ray
                               advancing. 

  nfastcr               0      Include fast ions (1 for inclusion) 

                               [Note: fast ions are treated as an
                                independent specie with temperature
                                =(2/3)*Energy of fast ions] 

  cpsio   (psi0)     0.99      Radial starting location for all rays: rho = psi0

  lcurdr                0      Adjoint green function not
                               calculated (if 0; if 1 calculated)

  lchoice (ichois)      2      Choice of wave dispersion
                               relation (=1 is high frequency
                               dispersion used in wave
                               propagation; =2 no frequency
                               limitation) 

  ldcur   (idcur)       1      Possible choices 1 or 3:
                               1 means an no frequency
                               limitation)alytic CD model,
                               3 means self-adjoint model

  ldmpsw (idmpsw)       1      Ion damping model:
                               =0 No ion damping;
                               =1 magnetized ion damping;
                               =2 unmagnetized ion damping
                                  (use with caution)

  lnalfa (nalfa)        1      Number of fast ion species
                               (must be 1 for now)

  lkalfa (kalfa)        0      0 -- ignore fast ion 
                                    damping
                               1 -- calculate unmagnetized fast 
                                    ion damping


 lnspect (nspect)       1      Number of toroidal wave-number bins 

 nraypts (nraypts)    6000    Number of coarse ray-steps 




 maxref  (maxref)    5        maximum number of edge reflections

 lslofa  (islofa)    -1       =-1   fast wave branch
                              = 1   slow wave branch


 cbmax    (bmax)    30        maximum Bessel function order 

 lrayio   (irayio)   0        =0  maximum data output to 'rayop' file, with absorption
                                  and current profiles plus ray data.
                              =1  only ray data with no absorption and current profile
                                  to 'rayop'.

 lcinc     (inc)     1        number of harmonics in ion-damping is 2*inc+1
  

 ebkev  (ebkev)      3.6e3    array holding fast ion birth
                              energy (in keV)
 liord (ioread)       0       =0 expects input file 
                              =1 expects input file
                               generated by one-two

 lcprint (iprint)     0       =0    output suppressed
                              =1    normal output
                              =2    more detailed output
                              =3    determine output at each call of OUTPUT1(x)
                              =-1   condensed information on ray tracing                               
                               
 lndvar (indvar)     1       =0 :  poloidal phase is used as independent variable in
                                    ray tracing
                              =1 :  total phase used as independent variable (recommended)   

4 ELECTRON_CYCLOTRON_RESONANCE_HEATING_(TORAY)

TORAY was installed in Transp in Decenber, 2003.
TORAY is a ray tracing code that is used for modeling heating and current 
drive during ECRH in tokamaks. Included below is a brief excerpt from the
NTCC documentation of TORAY (For more details about TORAY, please consult 
the NTCC modules web page: w3.pppl.gov/NTCC).

The TORAY ray tracing code computes contributions to electron cyclotron 
heating (ECH) and RF current-drive (ECCD) sources. TORAY now includes 
the recently developed ECCD module by Y.R. Lin-Liu which includes 
an adjoint formulation with collisionality correction factors 
that reduce the trapped electron fraction and increase the current 
drive efficiency. Other revisions include improving the power 
integration along the arc length, the addition of an aspect ratio 
dependence in the J/P current drive efficiency, and an improved 
evaluation of the poloidal angle used to calculate the local value 
of the major radius.

Below, we concentrate on accessing TORAY from
TRANSP and the associated inputs and outputs. Please consult 
the NTCC documentation on TORAY module for more information.   

5 TRANSP_NAMELIST_Controlled_Parameters_(Minimal_Set) 
  (Variables with Array at the bottom take more than one
   value, which could be different for each gyrotron)


NLTORAY           .F              Invokes TORAY if .T

NANTECH             1             Number of gyrotrons

TECHON*           0.0             Time when ECRH is turned on
(Array)                             (Set if P_ech(t) not provided)

TECHOFF*          0.0             Time when ECRH is turned off
(Array)                             (Set if P_ech(t) not provided)

POWECH*           0.0             POWER LAUNCHED (WATTS)
(Array) 

FREQECH           0.0             WAVE FREQUENCY (Hz)           
(Array)

XECECH            0.0             MAJOR RADIUS OF SOURCE (CM)
(Array)

ZECECH            0.0             HEIGHT ABOVE MIDPLANE OF
(Array)                                  SOURCE (CM)

PHECECH           0.0             Toroidal angle location of source
                                  (NOT the aiming angle, see PHAIECH)
                                  (Has no effect on axisymmetric simulation)

THETECH**         0.0             POLAR LAUNCH ANGLE OF
(Array)                           CENTRAL RAYS (DEGREES)
                                  (see below under Note about
                                   launch angles)
                                  **time dependent Ufile input now
                                  available:  PREECA & EXTECA

PHAIECH**         0.0             AZIMUTHAL LAUNCH ANGLE
(Array)                           OF CENTRAL RAYS (DEGREES)
                                  (see below under Note about
                                   launch angles)
                                  **time dependent Ufile input now
                                  available:  PREECB & EXTECB

*The ECH antenna power(s) P_ech(t) (one per gyrotron) are best set
time dependently by Ufile or MDS+ signal input.  When this is done,
the default is for TECHON/TECHOFF to be inferred from the power
trace data.

**In August 2010 the code was modified to allow polar aiming angle
(effects aiming in poloidal plane) and azimuthal aiming angle
(effects aiming in toroidal direction) to be specified as Ufile 
inputs.  Each Ufile gives the aiming of all launchers vs. time; the
number of launchers in the Ufiles must match the number (NANTECH) 
given in the namelist.

   PREECA = <Ufile prefix, polar aiming angles vs. time>
   EXTECA = <Ufile suffix, polar aiming angles vs. time>

   PREECA = <Ufile prefix, azimuthal aiming angles vs. time>
   EXTECA = <Ufile suffix, azimuthal aiming angles vs. time>

The Ufiles may also contain scalars giving the launcher (R,Z) locations,
frequency and divergence; if so these are checked against the namelist
values and the values must match.

If PREECA/EXTECA and PREECB/EXTECB Ufile data are not provided, then
the aiming angles are modifiable as step functions in time via namelist
updates.

TRANSP output scalar multigraphs THGYRO and PHGYRO record the time 
evolution of the THETECH and PHAIECH values, however they are obtained.

Note about launch angles:
------------------------

(DMC -- this description rewritten July 2008 based on suggestions of 
B. Harvey, but, the TRANSP definitions have not changed).

THETECH specifies the vertical or poloidal angle of rays relative to 
the +Z axis.  THETECH=0.0 yields rays pointing vertically straight up
(regardless of value of PHAIECH);  THETECH=180.0 specifies rays pointing 
vertically straight down (regardless of PHAIECH); THETECH=90.0 specifies 
rays in a horizontal plane, direction within that plane is set by PHAIECH.

PHAIECH specifies the toroidal aiming angle.  If THETECH is not 0.0 or 
+/- 180.0, the ray has a horizontal component; PHAIECH controls the
direction of this component.  For PHAIECH=0.0, the horizontal component
points in the +R direction, away from the machine axis of symmetry.  For
PHAIECH=180.0, the horizontal component points in the -R direction, towards
the machine axis of symmetry.  For PHAIECH=90.0, the horizontal component
is in the +Phi direction, pointing CCW around the machine axis when the 
machine is viewed from above.  PHAIECH=270.0 or -90.0 yields a horizontal
component in the -Phi direction.  This would be the direction to yield
CCW current drive (CW motion of electrons).

CW = clockwise.
CCW = counter-clockwise.  

Since a CCW EC beam drives electrons (e-, negative charge), a CCW EC 
beam results in a CW current.

Note that NLJCCW or Ufile input data specifies the direction of the main
plasma current.

5 Supplying_power_information_via_ufile

 The gyrotron power as a function of time and gyrotron
 number can be supplied in a Ufile. The ufile name is of the
 form prefix+shot#.ext (eg., power111203.ecrh where the shot# is
 111203). In the trdata section of the namelist, including
 prefix and extension with the ecrh trigraph ('ECP'), as below

 preecp='power' 
 extecp='ecrh'

 will enable trdat to read the ufile. This will supersede all
 the  powers specified via POWECH; normally the on/off times
 TECHON and TECHOFF are also reset by analyzing the powers but
 this can be overridden, forcing the namelist values to be used,
 by turning off NLECTFIX:

NLECTFIX (default TRUE) set on/off time from Ufile input data (if any)
                       no effect if power set from namelist.
 if NLECTFIX is true:
     PECTFIX  -- threshold power (watts if positive, -fraction
                 if negative) to define on/off times from input
                 power vs. time; default is -0.05, i.e. threshold
                 is 5% of the maximum power.
     DTECTFIX -- time to back off from threshold power times,
                 looking for actual zeroes in the input power.
                 default:  0.01 seconds.

Note that the EC launcher aiming angles can now be entered time
dependently with Ufiles, as described in the preceding section.

5 Additional_namelist_parameters_(TORAY)

The following are additional namelist parameters that
primarily affect the ``echin'' input file to TORAY.

NPROFTOR          41                NUMBER OF TORAY ZONES

TLASTOR                             LAST TIME TORAY RAY
                                    TRACING WAS DONE 

DTTOR           0.05                FREQUENCY OF CALLS TO 
                                    TORAY in seconds

NDAMPECH          2                 DAMPING MODEL
(Array)

NRAYECH          30                 NUMBER OF RAYS
(Array)

RFMODECH        0.0                 FRACTION OF RF POWER
(Array)                             LAUNCHED AS O-MODE

BHALFECH        1.7                 DIVERGENCE ANGLE (DEGREES)
(Array)                             (HALF ANGLE AT HALF POWER)

BSRATECH        1.0                 ASPECT RATIO OF BEAM
(Array)                             (1.0 FOR CIRCLE)

5 Additional_namelist_parameter_(TRANSP)

An antenna by antenna anomalous multiplier that can be applied to
the TORAY current drive profile outputs:

EFFECH          1.0                 EFFECTIVE CURRENT DRIVE
(Array)                             EFFICIENCY

5 TRANSP_namelist_parameters_for_TORAY_Namelist

The following are the TRANSP namelist variables that affect
the TORAY namelist (toray.in). Under normal circumstances
(especially for D3D), it is not necessary to modify these
values. However, for machines other than D3D, it is advisable 
to carefully examine these variables to make sure that they
are reasonable for the machine at hand. 

Below, the variables in parentheses are TORAY namelist variables
that correspond to TRANSP namelist variables. The user is urged
to consult the TORAY documentation on the NTCC web page
(http://www.pppl.gov/ntcc under Modules Library). 

NGAFITTOR (igafit)     1         Switch to call GAFIT 
                                 EFIT interface 
SMAXTOR   (smax)    2*RAXIS      Maximum arclength 
                                 of ray (cm) 
DSTOR     (ds)	      0.5        Initial step size 
                                 of arclength (cm) 
DSMINTOR  (dsmin)     0.25       Adjustable step size of 
                                 arclength (cm) depending 
		                 on power decreament 
FDOUTTOR  (fdout)     5.0        Ray output every 
                                 fdout step 
POWINCTOR (powinc)   1.0e13      Used get the J/P profile 
                                 along a ray for use by 
                                 CQL3D code 
RELERRTOR (relerr)   5.0e-5      Relative error tolerance in y-solution 
                                 vector of ODE solver, where 
                                 abs(local error) <= abs(y)*relerr+abserr
ABSERRTOR (abserr)   5.0e-5      Absolute error tolerance in ODE solver  
NHARMTOR  (nharm)      2         Harmonic number 
                                 (Crucial variable for current drive)
MN0TOR     (mn0)      32         Number of mesh pts in Gaussian integration 
                                 of Green's function in J/P resonance 
NGZNTOR (gauszone)     4         Number of annuli for 
                                 Gaussian ray pattern model 
                                  (range: 1 to 7)
MRAYTOR   (mray)                 Number of rays in ith Gaussian zone
(Array)                          (Maximum 7 zones: Defaults are
                                   /1 5 12 12 20 24 26/)
CRTOR     (cr)                    Azimuthal phase of ray pattern 
(Array)                           for ith zone (radians). Defaults are:
                                  /0.0 0.1 0.05 -0.05 0.05 -0.025 0.025/ 
MODELCTOR (modelc)     4          Lin-Liu module for ECCD calculation 

PWRFMNTOR (pwrfmn)   0.001       Minimum power (?)
NLCQLDAT  (cqldat)   .FALSE.     Switch to write CQL3D data files

5 TORAY_TRANSP_INPUT_(EXAMPLE)

 ! (Minimal set)

   NLTORAY=.T
   NANTECH=6
   TECHON=1.5
   TECHOFF=3.8
   FREQECH=110.e9,110.e9,110.e9,110.e9,110.e9,110.e9
   POWECH=.590e06,.450e06,.430e06,.360e06,.640e06,.000e06
   XECECH=239.73,239.73,239.99,239.99,239.36,239.99
   ZECECH=69.4200,69.4200,67.9400,67.9400,70.8300,67.9400
   THETECH=115.118,115.251,115.001,114.772,116.625,120.327
   PHAIECH=204.459,202.923,200.785,197.003,196.702,189.529

 !  (Additional parameters)

   NPROFTOR=41
   DTTOR=0.05
   RFMODECH=1.,1.,1.,1.,1.,1.
   BHALFECH=1.7,1.7,1.7,1.7,1.7,1.7
   BSRATECH=1.0,1.0,1.0,1.0,1.0,1.0
   EFFECH=1.0,1.0,1.0,1.0,1.0,1.0
   NDAMPECH=2,2,2,2,2,2
   NRAYECH=30,30,30,30,30,30

   TORAY input antenna powers via Ufile can be 
   checked using TRDAT (option E) 

5 Output_from_TORAY_(Accessed_using_rplot)

PEECH      ------ Profile of power deposition to
                  electrons (Watts/cm**3)

ECCUR      ------ Profile of ECRH Current drive
                    (Amps/cm**2)

EEGYRO     ------ ECRH Gyrotron Powers
(Scalar 
 multigraph)

EEHEATANT ------- Power deposition to
(Profile          electrons (Watts/cm**3) 
Multigraph)       for each antenna 

PECCURS   ------- ECRH Current drive
(Profile          due to each gyrotron 
Multigraph)       (Amps/cm**2)

In addition, the multigraph EEHEAT shows ECRH power deposited to electrons,
The multigraph PCURS includes ECRH driven current along with other currents.

5 TORAY_Data_For_Standalone_Runs

At up to 9 user selected times, data may be saved to allow the modular
toray code to be run in standalone mode. Sufficient data is saved 
to allow bit-for-bit reproduction of a TORAY calculation done at a
particular time in TRANSP, if the standalone code is run on a machine 
which is binary compatible with the machine on which TRANSP itself ran 
when producing the data.  If the standalone code runs on a machine 
which is not binary-compatible, the standalone rerun will not be 
identical bit-for-bit, but it will be "very close" to the original.

The saved data is a unix archive (tar file) compressed with gzip.  
Therefore, the data can only be unpacked on a unix machine which
supports tar and gzip. The contents of gzip files consist of the
inputs to TORAY, i.e. toray namelist (toray.in), the profiles 
and other wave related parameters (echin), the equilibrium (eqdskin)
in GEQDSK format, and the gafit.in file, and the output from TORAY,
i.e. the chout and toray.nc (netcdf) files. Unix-TRANSP includes 
Unix-TRANSP includes a script, codesys/csh/fi_gzn_unpack, to unpack 
the data.

The output times are specified in the namelist variable FE_OUTTIM(...):

  FE_OUTTIM(1) gives the time at which to write <runid>_TOR_TAR.GZ1
  FE_OUTTIM(2) gives the time at which to write <runid>_TOR_TAR.GZ2
     ...
  FE_OUTTIM(n) gives the time at which to write <runid>_TOR_TAR.GZn

  (1 <= n <= 9).

To unpack the GZn files, the fi_gzn_unpack script can be used 
(see fi_gzn_unpack_howto elsewhere in this document) or the unix
tar utility can be used, eg.

tar xvfz <runid>_TOR_TAR.GZ1

will unpack the contents to the current directory. As all the
GZn files contain files with the same names, please make sure to
unpack each GZ file in a different directory. 

Running standalone TORAY
-------------------------

To run stand-alone toray, you either require access to an installation of
TRANSP or a copy of toray installed locally.

Create a directory to unpack the gzipped 
file (<runid>_TOR_TAR.GZ1, etc.). Copy the gzipped files into the directory
and unpack it as instructed above. This will result in files of the type
psiin_anti, echin_anti, gafit.in_anti, toray.in_anti (among other files), 
where i in anti refers to the gyrotron number. Thus, for gyrotron 1,
they will be psiin_ant1, etc. For each gyrotron, copy the files into psiin,
psiin, echin, gafit.in, and toray.in, i.e.

cp psiin_ant1 psiin
cp echin_ant1 echin
cp gafit.in_ant1 gafit.in
cp toray.in_ant1 toray.in

Run toray with (if you have access to transp installation),

toray_transp

If you have your own installation of toray, you need to type
the corresponding executable.

4 ELECTRON_CYCLOTRON_RESONANCE_HEATING_(GENRAY)

GENRAY is a ray tracing code that can be used for modeling heating  
and current drive during ECRH in tokamaks. It has been developed 
and supported by Dr. Robert Harvey and his collaborators at 
ComPX. Although GENRAY can perform ray tracing calculations
for the Lower Hybrid and Higher Harmonic ICRH scenarios as well,
it is currently available for only ECRH in TRANSP. 
The GENRAY ray tracing code computes contributions to electron cyclotron 
heating (ECH) and RF current-drive (ECCD) sources.  

5 GENRAY_Namelist_Templates

An important characteristic of GENRAY that distinguishes it from
TORAY is the preparation of customized namelist template
for different tokamaks and, perhaps, different heating
scenarios. The namelist template is the most important input to
GENRAY. During the routine operation of GENRAY within TRANSP 
the relevant profiles and other ECRH specific input are copied
from a plasma state created during the TRANSP run and inserted into
the GENRAY input namelist creating an input namelist for a specific
time. 

Currently template namelist is available only for D3D.
The run will abort for all other machines if an attempt is
made to invoke GENRAY. For any other machine, please contact 
the transp support before embarking on a GENRAY ECRH run.
Enabling a GENRAY run for any other machine involves
development of a new template and physicists are expected to be
heavily involved in the development of the template. 
It might also require interaction with GENRAY developers headed
by Dr. Robert Harvey at ComPX. 

Below, we concentrate on accessing GENRAY from
TRANSP and the associated inputs and outputs. Please note that many
of the inputs and data input mechanisms (ufiles ,etc.) are
the same as for TORAY. These are pointed out as we encounter them
below.  

5 TRANSP_NAMELIST_Controlled_Parameters_(Minimal_Set) 
  (Variables with Array at the bottom take more than one
   value, which could be different for each gyrotron)
  These variables are put into the template namelist 
  each time GENRAY is invoked.


NLGEN_ECH          .F             Invokes GENRAY if .T

NANTECH             1             Number of gyrotrons

TECHON            0.0             Time when ECRH is turned on
(Array)                             (Set if P_ech(t) not provided)*

TECHOFF           0.0             Time when ECRH is turned off
(Array)                             (Set if P_ech(t) not provided)*

POWECH            0.0             POWER LAUNCHED (WATTS)*
(Array) 

FREQECH           0.0             WAVE FREQUENCY (Hz)           
(Array)

XECECH            0.0             MAJOR RADIUS OF SOURCE (CM)
(Array)

ZECECH            0.0             HEIGHT ABOVE MIDPLANE OF
(Array)                                  SOURCE (CM)

PHECECH           0.0             Toroidal angle location of source
                                  (NOT the aiming angle, see PHAIECH)
                                  (Has no effect on axisymmetric simulation)

THETECH           0.0             POLAR LAUNCH ANGLE OF
(Array)                                  CENTRAL RAYS (DEGREES)
                                  (see below under Note about
                                   launch angles)

PHAIECH           0.0             AZIMUTHAL LAUNCH ANGLE
(Array)                           OF CENTRAL RAYS (DEGREES)
                                  (see below under Note about
                                   launch angles)

*The ECH antenna power(s) P_ech(t) (one per gyrotron) are best set
time dependently by Ufile or MDS+ signal input.  When this is done,
the default is for TECHON/TECHOFF to be inferred from the power
trace data.

Note that as of 12/2005 only the power can be specified time 
dependently.  To add time dependence capability to the frequency 
or aiming angles would require a minor code change.

Note about launch angles:
------------------------

Please see the documentation under similar heading under TORAY.

5 Supplying_power_information_via_ufile

Please see the documentation under TORAY for this.


5 Additional_namelist_parameters_(GENRAY)

Some of the following are additional namelist parameters that
go into the template namelist.

TLASTOR                             LAST TIME TORAY RAY
                                    TRACING WAS DONE 

DTTOR           0.05                FREQUENCY OF CALLS TO 
                                    TORAY in seconds

BHALFECH        1.7                 DIVERGENCE ANGLE (DEGREES)
(Array)                             (HALF ANGLE AT HALF POWER)

BSRATECH        1.0                 ASPECT RATIO OF BEAM
(Array)                             (1.0 FOR CIRCLE)


5 Output_from_GENRAY_(Accessed_using_rplot)

See the similar item under TORAY for the outputs.

5 GENRAY_Data_For_Standalone_Runs

Running standalone genray requires access to TRANSP installation or
your own GENRAY installation.

The procedure for producing data for stand-alone GENRAY runs is the
same as it is for TORAY (see under TORAY_Data_For_Standalone_Runs). 
Once you have the zipped files, create a working directory and 
copy the zipped files. Unsip them as before (one at a time):

tar xvfz <runid>_TOR_TAR.GZ1 

This will produce, among other files, files such as
genray.in_i where i refers to gyrotron number and <runid>_ps.geqdsk.
For each gyrotron, copy genray.in_i into genray.in. Run genray
by typing (to use TRANSP version):

genray_transp 

4 NEUTRAL_BEAMS
Neutral beam injection parameters are specified through the namelist.

There are some special purpose programs to help with specification of
the rather voluminous neutral beam specifications.

5 Time_dependent_inputs
For most experimental analysis runs, it is best to provide the input
beam powers, voltages, and full/half/one-third energy mix time-
dependently.  These can be specified by a composite Ufile containing:

  time t, beam index 1:N,
    and:
  P_inj(t) (W) for 1st beam
  P_inj(t) (W) for 2nd beam
     ...
  P_inj(t) (W) for Nth beam

  E_inj(t) (V) for 1st beam
  E_inj(t) (V) for 2nd beam
     ...
  E_inj(t) (V) for Nth beam

  F_full(t) (current fraction) for 1st beam
  F_full(t) (current fraction) for 2nd beam
     ...
  F_full(t) (current fraction) for Nth beam

  F_half(t) (current fraction) for 1st beam
  F_half(t) (current fraction) for 2nd beam
     ...
  F_half(t) (current fraction) for Nth beam

I.e 4*N contiguously stored data channels.  A traditional TRANSP
program called "nbfile" can generate these types of Ufiles.  Various
sites have more modern procedures as well, e.g. an IDL procedure at
GA.

In the TRANSP namelist, time dependent neutral beam data is requested
by setting:

  NLBDAT=.TRUE.
  PRENB2=<Ufile prefix>
  EXTNB2=<Ufile suffix>

When time dependent data is used, the individual beam on and off times
are normally set by analyzing the power data for each beam, as described
in the following namelist controls.  To suppress this, using the namelist
TBONA and TBOFFA instead, set NLNBTFIX=.FALSE... When time dependent 
powers are given, the namelist controls can override to shorten the
pulse length of a beam, but the cannot lengthen the pulse as this is
controlled by the time dependent data itself.

NLNBTFIX (default T) set on/off time from Ufile input data (if any)
                       no effect if power set from namelist.
 if NLNBTFIX is true:
     PNBTFIX  -- threshold power (watts if positive, -fraction
                 if negative) to define on/off times from input
                 power vs. time; default is -0.05, i.e. threshold
                 is 5% of the maximum power.
     DTNBTFIX -- time to back off from threshold power times,
                 looking for actual zeroes in the input power.
                 default:  0.01 seconds.

5 Programs
In TRANSP, EXE points to where the programs are:  TRHOME:[TRANSP.EXE].

use EXE:PDX_ADDNBI to get PDX parameters from the scalar UFILE
into the TRANSP namelist.  The xnnnnn.NBI UFILE is created on the 
DAS-10 by program [66,165]GNBIUF from data in the archived BNRW file 
for shot nnnnn.

use EXE:PBX_ADDNBI to do the samething for PBX.  Does this program
work?  I don't remember testing it.
Caution-- the beam tangency radii vary in PBX.  They were constant in
PDX.

use the program EXE:NBFILE to set up the beam parameters
for a TFTR run.  TFTR beam "constants" are stored in a seperate file
(e.g. [TRANSP.TFTR]NBFIX86.DAT).  The user specifies variables (beam
powers, voltages, etc. through a table entry routine.  The code calc-
ulates the beam index for TRANSP, full/half/third energies, etc. and
enters these into the namelist for the run, REPLACING any old values
for these quantities.

**1986** NBFILE has been enhanced to input TFTR waveforms and write
a time dependent UFILE for TRDAT, containing beam powers, voltages,
and full/half/third energy fractions, for all beams.  Waveforms may
be examined and certain corrections (rescaling, timebase fixes, etc.)
are available.

WARNING - NBFILE.FOR must be changed when TFTR adds new beamlines
or if any beamlines are re-oriented.
5 General_controls
NLBEAM=.TRUE. to turn on the neutral beam model

NLBFPP=.TRUE. to use FPP beam model.
       .FALSE. (default) to use the standard Monte Carlo model.

NLSEED=.TRUE. and NSEEDI=<integer seed value> to control the random
number seed for a Monte Carlo simulation.  By default, the seed is
set differently for each run, from the system clock.  TRANSP runs
write their initial random number seed into their log file and into
a file <runid>TR.MSG, so that the seed can be reused, to exactly
reproduce a prior run.  The code version and build platform must
generally be IDENTICAL for this to work.

FPP beam model is being worked on, but is not currently recommended.

NBEAM=number of neutral beams (each fast neutral source counts as one)
DTBEAM=beam timestep.  Larger values make the code run faster but with
  poorer time resolution of beam code outputs and more "lag".  Typical
  values:  0.005 secs, PLT/PDX/PBX; 0.01 secs, TFTR.
GOOCON=numeric goosing (orbit code acceleration) parameter.  allows
  code to accelerate collision effects w.r.t. orbit effects for 
  computational efficiency.  R. Goldston's prescription
    GOOCON=5 "good but expeditious job"
    GOOCON=10  (compromise - TRANSP default)
    GOOCON=20 "excellent representation of banana transport" (slow!)

    (note -- a comparison of GOOCON=10.0 vs. GOOCON=30.0 was done
    on TFTR data by Mike Z, 6/92.  The runs are (in PPPL TFTR.90)
    are 52184A05 and 52184A06 and show no significant difference
    in results, comparing total and collimated DD neutron emission).

DTN=legacy orbit timestep control parameter-- defunct.  The setting of
  this parameter has no effect.

DTN_NBI_ACC = orbit timestep control (replacing DTN):  accuracy criterion 
  "per bounce" for orbit integration.
  The code interprets this somewhat conservatively, and the default
  value of 1.0e-3 is usually sufficient.  Reducing this to 1.0e-4
  will slow the code (NUBEAM) significantly and in standard regression
  tests there aren't any other change in observable outputs.

NPTCLS=constant census number of Monte Carlo ions to retain in slowing
  down beam ion population.  typically set to 1000.  runtime is 
  proportional to NPTCLS; Monte Carlo noise roughly inversely propor-
  tional to sqrt(NPTCLS).
  ** mod Sep 2003 ** no upper limit on NPTCLS or NPTCLF for fusion
  products -- fortran-90 dynamic memory allocation now used for
  particle lists.

NLFBM=.TRUE. to calculate beam distribution function.  Required for
  evaluation of beam-beam neutrons and for fast ion charge exchange
  spectrum simulations.  Note (June 2008): this is always forced to .TRUE.

(setting of NLFDEP is currently ignored).

EBDMAX= maximum energy tracked in distribution function.
  must be .gt. maximum injected neutral energy.

ABEAM = beam species (atomic weight).

NMCURB = 1 for calculation of (neoclassically shielded) beam driven 
  currents.  NMCURB=2 uses the simplified shielding correction 
  (1-Zb/Zeff).  NMCURB=0 suppresses all beam driven current.
  NMCURB=3 gives a more modern neoclassical shielding calculation.

  NMCURB=1 is neoclassical: Hirshman, Phys. Fluids vol. 21 No. 8 Aug 1978
  NMCURB=2 is Spitzer, (1-Zb/Zeff), (no trapping correction)
  NMCURB=3 is updated neoclassical:  Y.R. Lin-Liu, 
                F.L. Hinton, Phys. Plasmas 4 (1997) 4179
  NMCURB  = 4, shielding calculation by Honda M., Kikuchi M., Azumi M.
  "Collisionality dependence on shielding factor of beam driven current"
  Nuclear Fusion, submitted by October 2011. Martix inversion method are used
  to include collisionality dependence on a shielding factor at arbitrary aspect.
  NMCURB=0, no fast ion driven current.

DN0OUT = external neutral density - for orbits beyond the plasma
  boundary.  Set a large number e.g. 1.e11 for rapid charge-exchange
  loss of such ions.

WGHTA = Monte Carlo profile statistics control.  Default value is
  1.0, meaning that particles are weighted evenly across the profile.
  WGHTA = 20.0 favors statistics of particles deposited near the 
  plasma core, reducing variance in the heating profile computed
  there, at the expense of creating more statistical variance in the
  edge region.  WGHTA=20.0 works by creating more Monte Carlo particles
  with reduced weight near the core, and fewer particles with increased
  weight in the edge region, without changing the constant census as
  controlled by NPTCLS.  The higher the value of WGHTA, the stronger the
  numerical effect.  Especially for high density cases with poor beam
  penetration, WGHTA > 1.0 might be desirable.

  Changes of wghta will also change profile of MC beam ions average weight ('wbav') during orbiting.
  
  wbav = c*[(1-<x>)/WGHTA + <x>), 

  where 

  c = (wghtot/nnew) *SUM over j=1:mj ([(1-<x>)/WGHTA + <x>)*fdep(<j>)),

  here 

  fdep(<j>) is a probability of deposition to orbit averaged zone <j>

  fdep(<j>) = SDEP_OA(<j>,LSBEAM)/SUM(SDEP_OA(LCENTR:LEP1,LSBEAM))
 
  SDEP_OA  -- the orbit averaged new particles deposition profiles

  and wghtot/nnew 
  is the sum of WGHT actually deposited for subsequent orbiting, 
  divided by the number of MC ions actually deposited.

  Also wbav is renormalized for time dependence of power (everywhere it is used).
  PINJAY(ind,isb) -- is a new array for power of mc particles,at the time when these particles 
  were deposited.

  pinjay(IND,lsbeam) = pinjs(lsbeam) - bpshins(lsbeam)
	
  pinjs -- bem injected power by species 
  bpshins -- shine through power by species.



DXBSMOO = radial smoothing half-width (in r/a space).  Default
  value of 0.05 is recommended.

5 Deposition_Atomic_Physics_Options

(M. Gorelenkova & D. McCune Aug 2009) -- ADAS upgrade to NUBEAM
deposition model in progress).

Ground state deposition model based on ADAS (as alternative to
legacy PREACT database) is now available:

  I  0 LEV_NBIDEP = 1	! beam "deposision" model level:
                        ! 1 -- 100% PREACT atomic physics (ground state)
                        ! 2 -- 100% ADAS atomic physics (ground state)
                        ! 3 -- PREACT ground state atomic physics
                        !      with ADAS for impurities
                        ! 4 -- ADAS ground state atomic physics
                        !      with PREACT for impurities

A modern ADAS based excited states deposition model (to supersede the
May 1994 model) is in preparation but not yet ready as of Aug 2009.

NDEPMOD = Beam deposition model variation switch, default NDEPMOD=0.
  Set NDEPMOD=1 and XDEPMOD= enhancement_factor in order to modify
  the thermal plasma stopping cross-section for newly injected fast
  neutrals by the indicated factor.  This anomalous control affects
  beam deposition only; no other atomic physics calculation is
  modified.

(DMC May 1994)
A simple excited states deposition model has been installed in TRANSP.
To turn it on, set

  NSIGEXC=1

in the namelist.

The model computes an enhancement factor as a function of beam energy,
target plasma electron density, electron temperature, and Zeff.  
Target plasma ion temperature and target fast ion distributions are 
only taken into account in a rough manner.

The enhancement factor is applied to all fast neutral deposition and
charge exchange recapture processes equally (charge exchange and
ionization, beam-thermal and beam-beam).  The model for atomic 
processes for thermal neutrals is not affected.

The enhancement factor is applied to the standard TRANSP ground state
atomic physics model for beam deposition.  The enhancement factor is 
derived from an extension to lower energies of a fit described in the
paper by Janev, Boley and Post:

  "Penetration of Energetic Neutral Beams Into Fusion Plasma",
  Nuclear Fusion, Vol. 29, No. 12 (1989), pp. 2125-2139.

The enhancement factor nearly matches the "delta" plots in this paper.
However:  errors of ~5% in 1+delta are possible.  ~3% errors have been
observed.  The stopping cross section fit cannot be employed directly
because of differences in ground state atomic physics models.

The fit used is not the fit described in the paper but a fit based on
data provided via private communication, which extended the energy
range down to about 20 KeV/amu, i.e. relevant for TFTR beam energies.

TRANSP code references:  exc_dep library, sigfacz.for, sigfacx.for,
and sigmas.for.

RPLOT output multigraphs EXFS_H, EXFS_D, and EXFS_T show the excited
states effect for H, D, and T beams, respectively.  The model does
not apply to He beams.  Each multigraph has the excitation effect on
deposition of full, half and 1/3 energy beam neutrals, and the
averaged effect on charge exchange produced fast neutrals.

UPDATES (MG September,2009):

  NSIGEXC=0 means ground state model

  NSIGEXC=1 means "appropriate applicable" excited states model:
     ADAS for LEV_NBIDEP=2
     Janev-Boley-Post for other values of LEV_NBIDEP

  NSIGEXC=2 means Janev-Boley-Post applied to any model including ADAS.


The enhancement factor using  ADAS atomic physic for beam deposition is defined as:
 
enhancement factor (EF)
    EF = 
    S(Eb,N_e,T_i) * N_e / {<sig*v>_EI * N_e  +  SUM_i (<sig*v>_CX+<sig*v>_II)_i * N_i,}, 

where S(Eb,N_e,T_i) is beam stopping rate coefficient for ADAS excited state model (see ref.1)

    S(Eb,N_e,T_i) = SUM_i(Z_i * N_i *S_i(Eb,N_equv,T_i)) / SUM_i(Z_i*N_i).


   N_e - electron density,
   N_i - impurity density,
   < ... > - Maxwellian averaged,
   <sig*v> - is a function of (Eb,T_i) for ground state model
   Eb - beam energy,
   T_i - impurity temperature,
   EI- electron impact ionization,
   CX - charge exchange (non-neutralizing  and neutralizing when possible),
   II - impact ionization.


   H. Anderson et al. (2000) "Neutral beam stopping and emission in fusion plasmas I",
   Plasma Physics and Controlled Fusion Vol. 42, pp 781-806


Now, the enhancement factor is applied only for ionization  beam_thermal and 
beam_beam but NOT for charge exchange processes.

Enhancement factor for impact ionization (EF_ii) is defined as:

  EF_ii  = { EF * [(<sig*v>_CX+<sig*v>_II)_thermal + (<sig*v>_CX+<sig*v>_II)_fast] - 
            
            - <sig*v>_CX_thermal - <sig*v>_CX_fast }/[<sig*v>_II_thermal - <sig*v>_II_fast]



To include contribution from beam-beam reactions to the enhancement factor switches
	
  following setting supposed to be done in namelist:

  NLBBCX = .TRUE. 
  NBBCX_BB = 0

 In case if switch NLBBCX set .FALSE. no beam-beam contribution to deposition will be considered.
 If NBBCX_BB not equals ZERO then contribution from beam-beam reactions to the enhancement 
 factor will be NOT taken into account even if NLBBCX = .TRUE.

To calculate beam stopping coefficient for a beam-beam reactions average relative energy 
and RMS average from preceding time step will be considered as projectile relative energy and 
target temperature. They may be used on 2d spatial beam grid if swithch  NBBCX_AVG set ZERO or
they can be averaged over the flux surface and taken on  1d radial grid for 
NBBCX_AVG not equals zero.
	   
 
TRANSP code references:  exc_dep library, sigfacz_adas.for, getsigmas_adas.for and exc_sig.for

 NSIGEXC=3 

 ADAS310_FORTRAN_DRIVER has been implemented and validated in NUBEAM. 
 It is based on ADAS310 program from ADAS (Atomic Data and Analysis Structure) library. 
 The program calculate the exited population structure, effective ionization and
 charge-exchange coefficients of hydrogen atom(ions) and its isotopes in an impure plasma.
 A very many n-bundle-n approximation is used. ADAS310_FORTRAN_DRIVER provides
 users with atomic physics data computed in excited state model. This model is self consistent.
 To use this option in TRANSP/NUBEAM LEV_NBIDEP=2 and NSIGEXC=3 need to be set in namelist.

 NOTE:cross sections for a beam-beam reactions will be 
 computed in ground state model. There is a possibility to compute
 atomic data for an excited state model in approximation
 that fast ion distribution function is Maxwellian.
 FRANTIC module will remain in ground state model for an atomic state data.

TRANSP code references: adas310_fortran_driver library, getsigs_adas310
 
5 Deposition_Statistics_and_Data_Capture_Options

BEAM NEUTRAL TRACKS

All details of beam neutral tracks (per beam species) will be saved if 
time(s) for writing ACFILES - OUTTIM is/are set.  This data can be examined
with "get_fbm".  Deposition source function samples can be produced, shine-
through losses examined, statistics on trajectories plotted, etc.  By
default, all neutral beams are sampled in proportion to the rate at
which they inject particles into the tokamak (i.e. their beam current), 
but this can be modified by namelist control (see below).

NDEP0 = minimum number of deposition tracks to trace per step
(Monte Carlo control, typically set to 500).  This affects the noise
level in deposition model outputs (such as, the cold electron source
associated with beam deposition).  If MPI run this value will
be adjusted to the nearest multiple of the number of processes, i.e. so
that mod(ndep0,numproc)=0.  NDEP0 is also the size of the neutral track
sample gathered for "get_fbm" at OUTTIM-- although a smaller sample may
be gathered, if sampling is restricted to a specific beam and/or energy
fraction, and its fractional current is too low (see NDEP0_MAX).


!note:
gathering 50000 tracks when running on sunfire could be dangerous and
can cause an error related to memory unavailability.


NDEP0_MAX:  (only has an effect if NDEP_SET_BEAM is set):

If the selected beam source for which deposition data will be 
collected has beam source current less than 10% of the total beam 
current (summed over all beams), the number of tracks for collection 
will be min(f*NDEP0_MAX,NDEP0), where f is the fractional current for
the selected beam and energy fraction.  Default NDEP0_MAX = 100,000.
The idea is to constrain the total number of deposition calculations
attempted, in case the power on the selected beam NDEP_SET_BEAM tends
towards zero.

NDEP_SET_BEAM = beam source number for which deposition data will be gathered,
                between 0 and nbeam (number of beams in simulation).
                0 (default) means gather data for all available beam sources.
	        If ndep_set_beam set 0, then ndep_set_ien must be set 0.

		If there is no particle current for requested beam or
                this current is less than 1% of total ptcl. current then 
                collect track data for all beam sources and energy fractions.
                If particle current for requested beam is less than 10% 
                of total ptcl. current, a smaller sample may be collected
                (see description of NDEP0_MAX, above).

NDEP_SET_IEN =  energy fraction to be used when gathering deposition data 
                for a selected beam source(ndep_set_beam).
                1 - full energy fraction only
                2 - half energy fraction only
                3 - one third energy only
                0 - collect data for all energy fractions (default).

                IF there is only one energy fraction for a given beam source
                and NDEP_SET_IEN has been set equals 2 or 3, then NDEP_SET_IEN 
                will be reset to 1.

NLDEP0_GATHER = .FALSE. as a default, data will be gathered for only one 
                time step from tbm1 to tbm2, where tbm1=< OUTTIM(j)<tbm2.
                IF .TRUE. "track" data will be collected for
                multiple time steps from ~ OUTTIM-AVGTIM to OUTTIM.
                Track data storages will be expanded to 
                ndep0*[number_time_steps], may be DANGEROUS for memory.
                Set NDEP0_MAX_GATHER to constrain the total number of
                tracks gathered, by reducing the time window for gathering.
                NDEP0_MAX_GATHER=100000 by default (a safe value for memory
                considerations is not currently known).

TRANSP code references:  exc_dep library, sigfacz.for, sigfacx.for,
and sigmas.for.

ION SOURCE AT BIRTH

User can get just the list of ions actually deposited for subsequent following in orbiting. 
This did not depend on NDEP0 but  rather on our census control based on NPTCLS.

As an output for successful TRANSP/NUBEAM run user will have files <RINID>_birth.cdf<nn> in $RESULTDIR/<TOKID>  directory,
<nn> -- is a number related to OUTTIM(nn) and is consistent  with <RINID>.DATA<nn>. 

TRANSP/NUBEAM_COMP_EXEC  standalone program (nbi_pserve = -1):
Everything is the same as above except the name for output files -- <RINID>_nubeam_birth.cdf<nn>.

For NUBEAM_COMP_EXEC and MPI_NUBEAM_COMP_EXEC the output files will be kept in main directory from where program was started.
Control switch NLDEP0_GATHER in NUBEAM namelist allows accumulation of this data from all steps (NLDEP0_GATHER = .true.)
or only for the last one if NLDEP0_GATHER = .false.

To get this data from TRANSP run user need to set OUTTIM(nn), AVGTIM, NLDEP0_GATHER (.false. is a default).

5 _2d_geometry
The beam code evaluates various effects (e.g. beam-beam interactions)
on a 2d grid vs(rho,theta).

The resolution of this grid is controlled by NZONE_FB; the following
settings are typical:

  NZONE_FB=10  ! standard resolution (default)
  NZONE_FB=20  ! doubled resolution

Other values of NZONE_FB can be chosen, but, the numbers of TRANSP 
zones (NZONES), beam radial zones (NZONE_NB) and Fokker Planck code 
radial zones (NZONE_FP) must ALL be exact integer multiples of NZONE_FB.

Typical TRANSP settings:
  NZONES=20 (20 plasma zones)
  NZONE_NB=20
  NZONE_FP=20
  NZONE_FB=10 (10 beam zone rows)

Typical TRANSP settings with increased radial resolution:

  NZONES=100 (100 plasma zones)
  NZONE_NB=100
  NZONE_FP=20
  NZONE_FB=20 (20 beam zone rows)

The number of poloidal zones per zone row goes up linearly with the
row index.  There are appoximately nzone_fb*nzone_fb/2 total zones--
i.e. doubling the radial resolution increases the total number of
two-dimensional grid zones by a factor of four.

5 Beam_parameters
choose subtopic
6 fixed_controls
NB dmc Oct 2003 -- controls which *do* vary from beam to
beam are now available for these items...

THESE CONTROLS DO NOT VARY FROM BEAM TO BEAM

NBSHAP=1: rectangular ion sources
  BMWIDR= half-width (cm)  BMWIDZ= half-height (cm)
NBSHAP=2: circular ion source
  BMWIDR= radius (cm)

OLD NAMELIST CONTROLS ***>
the beamline aperture (into vacuum vessel) is assumed rectangular.
  REDGE= half-width of aperture (radius, if aperture is circular)
  XZEDGE=half-height of aperture (ignored, if aperture is circular)
DMC 9 May 1991 -- variable aperture controls are now available, and
more appropriate, since the aperture shape is controlled on a beam
by beam basis.  see "variable_controls".

FOCLR= horizontal focal length of beam (cm)
FOCLZ= vertical focal length of beam (cm)

DIVR= horizontal divergence of beam -- radians.
      if xl0 = dx/dl of the beamlet centerline, the actual beamlet
      has probability distribution 
           P(dx/dl) ~ exp(-(dx/dl -xl0)**2/(2*DIVR**2))
      with P(xl0 +/- sqrt(2)*DIVR) = (1/e)*P(xl0).  Some define the
      "half-angle" (a/2) to be the deviation at which the probability
      density is (1/e) of the peak density.  Then DIVR = (a/2)/sqrt(2).

      DIVR is the spreading parameter for [dx/dl] to be given to a
      "normal" (Gaussian) probability distribution function.

      for NBSHAP=2 (circular source) DIVR is the vertical divergence
      as well.
      
DIVZ= vertical divergence of beam -- radians.  probability distribution
      form and normalization is exactly analogous to DIVR-- describing
      the beam spreading dz/dl about a centerline value.

      DIVZ is used for rectangular sources only.
      for NBSHAP=2, DIVZ is not used.

6 variable_controls
for the ib'th beam, ...

EINJA(IB) = full injection energy of beam (eV)
PINJA(IB) = power injected by beam (WATTS)
TBONA(IB) = beam turn on time (seconds)
TBOFFA(IB)= beam turn off time (seconds)

PDELTA(IB)= (no longer used, retained for namelist compatibility)

RTCENA(IB)= beam tangency radius (cm - dist to tokamak centerline)
FFULLA(IB)= ptcl/sec (or beam current) fraction of beam neutrals which 
            are at full beam energy
FHALFA(IB)= fraction of beam neutrals injected at half energy
            (1.0-FFULLA(IB)-FHALFA(IB) = fraction at 1/3 energy)

Note: if CUR(IB) is the current (A) on beam #IB, then this relation is 
      satisfied:  PINJA(IB) = CUR(IB)*(FFULLA(IB)*EINJA(IB) + 
                          FHALFA(IB)*(EINJA(IB)/2) +
                          (1.0-FFULLA(IB)-FHALFA(IB))*(EINJA(IB)/3))

XLBTNA(IB)= distance, ion source to beam tangency radius
XYBSCA(IB)= elevation of beam ion source above/below midplane
NLCO(IB)  = .TRUE. if the beam is CO-injecting with the plasma
            current.
XBZETA(IB)= toroidal angle of the beam source in an (R,zeta,Z)
            right handed coordinate system (deg).

If the following are defaulted, the scalar controls NBSHAP, FOCLR,
FOCLZ, DIVR, and DIVZ are applied to ALL beams:

NBSHAPA(IB) -- ion source grid shape of each beam
               1 = rectangle, 2 = circular
BMWIDRA(IB) -- source grid radius (if circular) or half-width 
               (if rectangular)
BMWIDZA(IB) -- source grid half-height (if rectangular)
               (ignored if NBSHAPA(IB)=2).

FOCLRA(IB) -- horizontal focal length (cm) of each beam
FOCLZA(IB) -- vertical focal length (cm) of each beam
              (only used if NBSHAPA(IB)=1)

DIVRA(IB) -- horizontal divergence (radians) of each beam
DIVZA(IB) -- vertical divergence (radians) of each beam
              (only used if NBSHAPA(IB)=1)


  Required 1st aperture into vacuum vessel:
  -----------------------------------------
XLBAPA(IB)= distance, ion source to beam aperture into Vacuum Vessel
  (this is the distance of the beam centerline from the ion source to
  the plane containing the aperture, which is assumed to be perpendicular
  to the beam centerline)
XYBAPA(IB)= elevation of beam centerline above/below plasma midplane
  when it passes through the aperture
NBAPSHA(IB)= aperture shape 1=rectangular (default)  2=circular
RAPEDGA(IB)= aperture horiz half-width or radius if aperture is
   circular (default = scalar REDGE, see "fixed_controls")
XZPEDGA(IB)= aperture half-height, if aperture is rectangular
   (default = scalar XZEDGE, see "fixed_controls")

New DMC Aug 2009:  Aperture offsets can be defined.  Default is that the
  offsets are zero, i.e. by default the apertures are centered around the
  beam centerline.  Offset feature added per request of DIII-D scientists.
XRAPOFFA(IB) radial offset of aperture relative to beam centerline: a 
  positive value shifts the aperture out in major radius, favoring beam
  neutral trajectories with tangency radius greater than the beam 
  centerline tangency radius (RTCENA(IB)).
XZAPOFFA(IB) vertical offset of aperature relative to beam centerline.
  A positive value shifts the aperture upward relative to the beam 
  centerline.

  Optional 2nd aperture into vacuum vessel:
  -----------------------------------------
XLBAPA2(IB)= distance, ion source to 2nd aperture into Vacuum Vessel
   (default 0.0 = NO SUCH APERTURE)
NBAPSH2(IB)= aperture shape:  default 0= NO SUCH APERTURE;
   1=rectangular 2=circular
RAPEDG2(IB)= aperture horiz half-width or radius if aperture is
   circular (default = scalar REDGE, see "fixed_controls")
XZPEDG2(IB)= aperture half-height, if aperture is rectangular
   (default = scalar XZEDGE, see "fixed_controls")

New DMC Aug 2009:
XRAPOFF2(IB) radial offset of 2nd aperture (definition analogous to 
   XRAPOFFA(IB) for the main aperture).
XZAPOFF2(IB) vertical offset of 2nd aperture (definition analogous to 
   XZAPOFFA(IB) for the main aperture).

Note BOTH NBAPSH2 AND XLBAPA2 must be set to obtain modeling of 
a 2nd aperture in the Monte Carlo deposition routine.
6 Beam_Trace_Elements
(New dmc Aug 1993) (Reviewed & updated dmc May 2010)

TRANSP now supports an option for trace elements in beam lines.
A trace element is a second species that is up to 10% of the
concentration of the main species in the beam line (example:
trace of T in a D beam).  NOTE: this feature is only available
if time dependent waveforms of beam power and voltage are input
through trdat, i.e. NLBDAT=.TRUE.

To access this feature, set up the main species beam in the
usual way; let ib be the index to this beam line in the TRANSP
namelist; let nb be the number of main species beams.  Then,

    NTRACE(nb+1)=ib    ! model trace element in beamline ib
    FTRACE(nb+1)=0.02  ! 2% trace
    XZBEAMA(nb+1)=1.0  !  trace element Z
    ABEAMA(nb+1)=3.0   !  trace element A

    NTRACE(nb+2)= ...  ! addl trace element specifications...

Set the namelist value of NBEAM to: nb + [#beams with trace elements];
(or the beam namelist setup software should do this).

Note that each main beamline can have either no trace elements or a
single trace element; multiple trace elements per beamline is not
currently supported.

As far as TRANSP is concerned, the trace element is an entire
new beam species, with its own complement of Monte Carlo 
particles and (if the trace element is an isotope of H or He) with 
a corresponding thermal specie slot required in the target plasma.

(If the main beam specie or trace element is a noble gas specie, a
corresponding thermal specie slot is not required).

The FTRACE(ib) specification causes 2% of the power of beam
ib to be diverted from the main beam power into this "trace
beam".

Some beam namelist setup programs have been upgraded to allow an 
option for setting up trace element beams.  The presence or absence 
of trace element beams should not affect the NBFILE beam power Ufile
output.

TRACE BEAM ENERGY FRACTIONS:  If either the main beam element
or the trace element is not an isotope of Hydrogen, then, the
trace beam is treated as injected 100% at full energy.

If both the main beam element and trace element ARE Hydrogen
isotopes (as in a T trace in a D beam), the trace beam uses the 
same energy fractions as main beams, based on whatever data is
provided for this.  (Note: the ability to override this default
has been removed from the code).

If both the main beam element and trace element are Hydrogen
isotopes, the energy levels of the less than full energy beam
fractions are not 1/2 and 1/3 as in the main beams, but
are determined by the the mass ratio of the trace isotope
to the main isotope.  For example, for a T trace beam in
a D main beam, the "half" energy species is actually

    E(1/2) = 3 / (2 + 3) = 3/5   (DT molecule assumed)

and the "third" energy species is actually

    E(1/3) = 3 / (2 + 2 + 3) = 3/7   (DTD molecule assumed).
    
6 Beam_ontime_override

Normally, TRANSP requires that the start time of a run be
earlier than the earliest beam turn-on time, i.e.

  TINIT .le. {min of all TBONA(ib),ib=1 to nbeam}

Violation of this condition results in the error:

 *** ERROR IN FDATCHK *** 
     TINIT MUST BE .LE. TBON

In TRDAT.

But, this can be overridden, without changing other data,
by setting

  TBONMIN = <desired beam on time (.ge. TINIT)>.

in which case no beams will be turned on until time TBONMIN
at the earliest, even if for a particular beam ib, TBONA(ib)
comes earlier.

5 Debug_switches
These default .TRUE.:
NLBCPA=.FALSE.  to suppress fast ion pitch angle scattering
NLBCOH=.FALSE.  to suppress OH acceleration of fast ions
NLBCDE=.FALSE.  to suppress energy diffusion while slowing down
default value:  never
TORBO = time to revert to *COLLISIONLESS ORBITTING* and SUPPRESS
  DEPOSITION OF NEW BEAM IONS.  TORBO.gt. beam on time required.
  This switch turns off all collisional effects and cx and 
  compression.  The fast ion orbits should in principle be fixed
  in place.

5 Anomalous_Diffusion
An anomalous radial diffusion model exists for Monte Carlo and RF
fast ions.

New March 2010: A set of input profiles Df(E,x,t) can now be introduced,
specifying diffusivity with dependence full 2d dependence on energy and
radial flux coordinate, and with an orbit topology based dependence on
velocity pitch.  This option is activated with NMDIFB=4.  See subtopic:
New_3d_Anom_Diffusion.

New by Emil Ruskov Dec 1994 -- use NMDIFB=3 and D2F profile Ufile
to specify time and space varying anomalous diffusivity directly;
(Sep. 2007: V2F profile added).

Set NMDIFB=1,2, or 3 to turn on the 1d fast ion transport model.  (NMDIFB=0,
no radial transport, is the default; details on meaning of NMDIFB .gt. 0 
given below).  Set NMDIFB=4 to turn on the high-dimensional model (see the
subtopic).

For NMDIFB=1,2, or 3:
  Set NKDIFB=1 to apply model to beam & RF fast ions (default)
      NKDIFB=2 to apply model to fusion product fast ions
      NKDIFB=3 to apply model to all fast ions
(For NMDIFB=4 there is a different mechanism for species dependence; see
subtopic New_3d_Anom_Diffusion).

NOTE: NMDIFB=1 and NMDIFB=2 are seldom used.  Usually it is best to control
the radial transport explicitly with input data:  NMDIFB=3 or =4.  Usually,
NMDIFB=1 is used only to set a radially invariant diffusivity, specified
with BDIFB=CDIFB=<the desired diffusivity, cm**2/sec>.

Control the diffusivity as follows:

  Db = D2F Ufile data (if NMDIFB = 3) or
       min( CDIFB, max( BDIFB, (ADIFB * De) ) ) 

  NEW Sep. 2007:
  If D2F Ufile data is provided (NMDIFB = 3) a velocity may also
  be provided as the V2F Ufile: fast ion transport for species b
  will then be:   -Db*grad(nb) + vb*nb; Db from D2f; vb from V2F.
  V2F added DMC September 2007

where the namelist scalar inputs are

  ADIFB = MULTIPLIER on electron particle diffusivity computed by 
          TRANSP
  BDIFB = minimum permissable diffusivity (cm**2/sec) .ge. 0.0
  CDIFB = maximum permissable diffusivity (cm**2/sec)

and De is defined according to the value of the switch NMDIFB:

  NMDIFB=1 --> De = electron particle diffusivity from electron flux
  NMDIFB=2 --> De = electron particle diffusivity from Ware-pinch
               corrected flux.

Note:  to eliminate the dependence on De and get a constant 
anomalous diffusivity, set BDIFB=CDIFB=constant.

and note ALSO:

  NMDIFB=3 --> input Db directly from D2F profile Ufile input
               input vb directly from V2F profile Ufile input
                   resulting flux will approximate
                      -Db*grad(nb) + vb*nb
                   in limit of sufficient number of MC ptcls.

6 Conserved_quantities
The anomolous transport model is coded to preserve the following
orbit quantities of transported fast ions when ever possible[*]:

Total energy     Etot = Epot + Ekin   (in the lab frame)
Magnetic moment    mu = v_perp^2/B

[*] exceptions: 
   (a) if conservation of (Epot + Ekin) would result a negative Ekin,
       this is not permitted; instead Ekin is set to a very small value
       and Etot is not conserved exactly.  Since NUBEAM is a fast ion 
       model that stops following particles when they reach the local
       3/2 Ti (in the rotating plasma frame), usually plenty of kinetic
       energy is available.  But it is not impossible; in a case with
       extreme rotation, lab frame Ekin=0 may correspond to a particle 
       with energy greater than 3/2 Ti in the plasm frame.
   (b) if conservation of mu would require v_perp/v greater than one, 
       this is prevented; v_perp = v is substituted and mu is not 
       conserved exactly.  This could happen if the model applies
       inward diffusion (towards a region of increased |B|) to a trapped 
       orbit near its banana tip.  (The diffusion operator could be
       modified to prevent such motion, but this is not in the code
       as of April 2010).

6 New_3d_Anom_Diffusion

This option applies if the TRANSP namelist specifies NMDIFB=4.
CAUTION: NMDIFB=4 is implemented in NUBEAM only.  There is no NMDIFB=4
operator in the RF fast ion Fokker Planck package as of this writing 
(D. McCune Apr 2010).

(Up to) 6 3d Ufile inputs may be provided to specify diffusivity profiles
vs. (fast ion lab frame kinetic energy, fast ion orbit averaged radial 
position, time):

   FD0(TIM,ENG,XXX)  { 'FD deeply trapped',       'cm**2/sec' }
   FDB(TIM,ENG,XXX)  { 'FD barely trapped',       'cm**2/sec' }
   FDP(TIM,ENG,XXX)  { 'FD co barely passing',    'cm**2/sec' }
   FDQ(TIM,ENG,XXX)  { 'FD co passing limit',     'cm**2/sec' }
   FDR(TIM,ENG,XXX)  { 'FD ctr barely pass.'  ,   'cm**2/sec' }
   FDS(TIM,ENG,XXX)  { 'FD ctr passing limit',    'cm**2/sec' }

The user provided 3d Ufiles can have any axis ordering, but the axes'
physical units must be correctly labeled, so that the time and energy 
and radial grid axes can be correctly identified.  If any input Ufile does 
not define the "MY_NRI" scalar, then, the definition of the radial flux 
coordinate is user selectable using the namelist controls, separate for 
each Ufile:  NRIFD0, NRIFDB, etc.  The interpretation is as with f(x,t) 
Ufile inputs to TRANSP; in all cases the expected x range is [0:1]:

  NRIxxx = +/-5 --> sqrt(enclosed_toroidal_flux/toroidal_flux_at_bdy)
  NRIxxx = +/-6 --> enclosed_poloidal_flux/poloidal_flux_at_bdy
  NRIxxx = +/-7 --> sqrt(enclosed_poloidal_flux/poloidal_flux_at_bdy)
  NRIxxx = +/-8 --> enclosed_toroidal_flux/toroidal_flux_at_bdy

No other NRIxxx values are allowed.

If the Ufile(s) do contain MY_NRI scalars, then that scalar's value
sets NRIxxx (here xxx means, one of {FD0,FDB,FDP,FDQ,FDR,FDS}).

Lower-dimensional Ufiles may be provided: if e.g. there is no energy
grid, then the specified diffusivities apply at all energies.  Correct
labeling must be provided so that Ufile grid axes can be unambiguously 
identified.

Note: the following restriction exists in the current implementation:
all inputs {FD0,FDB,FDP,FDQ,FDR,FDS} provided must be defined over the
same matching energy grid.

The combined set of diffusivity profiles defines a pitch dependence based 
on orbit topology.  Each time a new first orbit is started, a single "un-
goosed" orbit is run first without diffusion, in order to establish orbit 
topology parameters and an estimate for orbit numerical acceleration 
("goosing") that takes expected diffusion rates into account.

The actual diffusivity for the current orbit varies in pitch-space is 
evaluated in NUBEAM as described below.  It should be noted, to take 
into account the presence of a radial electrostatic field, a nominal
angular velocity omega_ExB is computed, which provides a definition
for a reference frame where Er=grad(potential) can be ignored (it 
corresponds to a velocity where the Lorentz vxB force cancels the
radial electrostatic force on charged particles).  This frame recovers 
the conventional behavior of v_pll=0 at trapped orbit reflection points.
References to v_pll that follow refer to the omega_ExB reference frame
(v_perp is unchanged by the frame transformation).  It is also necessary to 
use total velocity (or speed) v in this frame to obtain accurate 
estimates of B_refl = B*(v/v_perp)**2 of the field strength necessary
for orbit reflection (trapping) based on conservation of mu=v_perp**2/B.

Let:
  <v_pll> = half-orbit-bounce averaged vpll = sign*v.B/|B|, with
sign = +1 if the toroidal field and toroidal current are parallel; -1
if they are anti-parallel.  For orbits deemed passing, <v_pll> > 0 will
indicate a "co" orbit (with the plasma current); <v_pll> < 0 will 
indicate a "ctr" orbit (against the plasma current).

  B_max(orbit) = max |B| seen by an orbit guiding center on the last
half bounce;

  x_Bmax(orbit) = flux surface at which B_max(orbit) is seen;

  B_refl(orbit) = B_max(orbit)*(v/v_perp)**2 at the point in the last
half bounce where B_max(orbit) is encountered (to be precise, in units
of cm/sec, max(1.0,v_perp) is used in the denominator of this expression).

If (comparing midplane B values to B_max(orbit)) the orbit shows finite
"banana" shaped indentation, AND, B_refl/B < 1.02, the orbit is deemed 
trapped, with normalized trapping depth

  d_trap = (Bmax(x_Bmax)-B_max(orbit))/(Bmax(x_Bmax)-Bmin(x_Bmax))

where Bmax(x_Bmax) and Bmin(x_Bmax) are the maximum and minimum |B| on
the x_Bmax(orbit) flux surface; d_trap--> 1.0 indicates a deeply trapped
orbit, hovering near the flux surface Bmin; d_trap--> 0.0 indicates a 
barely trapped orbit, almost but not quite making it through Bmax(x_Bmax).

If these conditions are not satisfied, the orbit is treated as passing,
co or ctr according to sign(<v_pll>), and with normalized passing depth

  d_pass = 1.0 - B_max(orbit)/B_refl(orbit)

Note that d_pass --> 1.0 indicates a "deeply passing" orbit satisfying
B_refl(orbit) >> B_max(orbit); d_pass --> 0.0 indicates a passing orbit
close to the trapped-passing boundary, B_refl(orbit) near B_max(orbit).

These criteria are determined at/near midplane crossings once every half
bounce, and apply to the diffusion applied for the following half bounce.

(ST-tokamak fast ion orbits which do not reach the midplane are treated 
as deeply trapped, d_trap=1.00).

For co-passing orbits (<v_pll> > 0) the diffusivity is:

  D = D_FDP*(1-d_pass) + D_FDQ*d_pass;

For ctr-passing orbits (<v_pll> < 0) the diffusivity is:

  D = D_FDR*(1-d_pass) + D_FDS*d_pass;

For trapped orbits the diffusivity is:

  D = D_FDB*(1-d_trap) + D_FD0*d_trap.

The variation of D with lab frame ion energy (E) and radial flux coordinate
position (x) track the variation of (E,x) around the orbit.
---------------

If the FD0 Ufile is omitted, the "deeply trapped orbit" diffusivity is
zero; equivalent interpretations are applied to FDB, FDP, and FDQ.

If FDR is omitted, FDP data is applied, i.e. the "co barely passing"
diffusivity applies also to "ctr barely passing" orbits.

Similarly, if FDS data is omitted, FDQ data is applied to "ctr passing
limit" orbits.

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

The diffusivity is used to move the fast ion in a random walk in (R,phi,Z)
space throughout orbiting.  "Goosing", NUBEAM's numerical orbit integration
accelleration based on time scale separation tau(other-physics)/tau(bounce)
is attenuated to keep the random walk step sizes small, if possible.  The
diffusion time scale is based on the maximum of near by diffusivities seen,
averaged over each half bounce.  For each orbit in each NUBEAM macro time
step, a half orbit bounce is evaluated with goose=1.00 first, in order to
probe the physics time scales, before computing the first half orbit with
goosing acceleration enabled.  "Goosing" is an important performance
feature of NUBEAM, typically enabling the code to operate 10x to 1000x 
more efficiently than if this were not implemented.

7 Species_dependence_3d_anom

Namelist controls can be used crudely to introduce a variation in the 
strength of the NMDIFB=4 diffusion operator with fast ion specie:

  TMUL_H_BEAM_IONS = 1.0   ! Df(E,x) transport multiplier, H beam ions
  TMUL_D_BEAM_IONS = 1.0   ! Df(E,x) transport multiplier, D beam ions
  TMUL_T_BEAM_IONS = 1.0   ! Df(E,x) transport multiplier, T beam ions
  TMUL_He3_BEAM_IONS = 1.0   ! Df(E,x) transport multiplier, He3 beam ions
  TMUL_He4_BEAM_IONS = 1.0   ! Df(E,x) transport multiplier, He4 beam ions

  TMUL_H_FUSION_IONS = 1.0   ! Df(E,x) transport multiplier, H fusion ions
  TMUL_T_FUSION_IONS = 1.0   ! Df(E,x) transport multiplier, T fusion ions
  TMUL_He3_FUSION_IONS = 1.0   ! Df(E,x) transport multiplier, He3 fusion ions
  TMUL_He4_FUSION_IONS = 1.0   ! Df(E,x) transport multiplier, He4 fusion i

These apply ONLY for nmdifb=4.  When nmdifb=4, the namelist control nkdifb
has NO effect.

As indicated, the default values are 1.00, specifying no species dependence:
use the FD0,FDB,FDP,FDQ,FDR,FDS data as given on all fast species.

7 Radial_variation_effects

If a spatially varying diffusivity D applies to some class of Monte Carlo
particles, a random walk Monte Carlo diffusion operator yields an average 
flux

    <gamma> = -D*grad(n) -n*grad(D)

with n the resulting density of the affected class of particles.

The second term is important.  In the model, particles tend to be ejected
from high diffusion regions but confined in low diffusion regions which
accounts for the -n*grad(D) contribution to the average flux.  

In nmdifb=3, a counterbalancing velocity v=grad(D) is introduced to produce
instead an expectation value of <gamma> = -D*grad(n) so that the behavior
resembles that of diffusion operators in fluid transport models.  (This 
is part of the definition of nmdifb=3 -- it is anomolous diffusion, meaning,
there is no physics justification required, it is just a modeling tool).

There is no such counterbalancing velocity in the nmdifb=4 model!  This
can lead to very strong local effects, particularly if -n*grad(D) points
inward near the magnetic axis: fast ion density can become locally peaked
to high values in the low valume axial region.  If this results in fast 
ion density exceeding electron density locally, it will stop the TRANSP 
run.

As of Apr 2010 there is no mechanism for supplementing the nmdifb=4
diffusion operator with a velocity or "pinch" term (but it could be done).

6 Time_dependence_option

(these controls have NO effect if NMDIFB=3 or NMDIFB=4 Ufile input 
options are in use)

The controls ADIFB, BDIFB, and CDIFB may now be given as step
functions varying in time, using the following namelist arrays,
each of which may contain a maximum of 8 elements:

TDIFBA(...):  ADIFB, BDIFB, CDIFB transition times (seconds).
  **times must be given in strict ascending order**
ADIFBA(...):  ADIFB is set to ADIFBI(i) from time TDIFBA(i) to
  time TDIFBA(i+1).  If TDIFBA(i+1) is omitted it is set equal
  to FTIME, the stop time of the run.
BDIFBA(...):  BDIFB for the various time intervals (cf ADIFBA)
CDIFBA(...):  CDIFB for the various time intervals (cf ADIFBA).

for times prior to TDIFBA(1), the original namelist supplied values
of ADIFB, BDIFB, and CDIFB continue to apply.

Example:

NMDIFB=1   ! turn on anomalous diffusion model
BDIFB=0.0  ! but have zero anomalous diffusivity initially
CDIFB=0.0  !  by setting BDIFB=CDIFB=0

TDIFBA=3.1,3.3,3.5   ! anomalous diffusivity transition times
BDIFBA=1.0e3,1.0e4,2.0e4  ! anomalous diffusivities at/after
CDIFBA=1.0e3,1.0e4,2.0e4  ! transition times

This gives 0.0 diffusivity for t=TINIT to 3.1 seconds
           1.0e3 diffusivity for t=3.1 to 3.3 seconds
           1.0e4 diffusivity for t=3.3 to 3.5 seconds
           2.0e4 diffusivity from t=3.5 seconds to the end of the
                 run.

Note that the transition times are implemented at the beginning
of beam timesteps; diffusivity cannot vary within beam timesteps,
so, diffusivity time intervals which are short compared to the 
beam model timestep size (DTBEAM) will not be resolved!

6 Energy_dependence_option

This option is for NMDIFB=1,2, or 3 only.  No effect on NMDIFB=4!

The Monte Carlo code allows fast ion anomalous diffusion to be
specified as a function of fast ion energy.  The method is to
specify via the namelist a piecewise linear function giving the
energy dependence.  This function is itself independent of all
other coordinates (space, time, specie index).

Note this feature is in the Monte Carlo code only -- not the
FPP code.

The namelist arrays to set are:

EDIFBE(...) -- strictly ascending list of energies (eV).
  Lab frame fast ion energies, max of 20 values.
FDIFBE(...) -- corresponding list of anomalous diffusivity
  correction factors **between 0.0 and 1.0**.

FDIFBE(...) gives multiplicitive factors applied to the
anomalous diffusivity computed from ADIFB, BDIFB, CDIFB, etc.
as described in the preceding section.

Example:

EDIFBE=40000.0, 60000.0, 70000.0  !energies
FDIFBE= 1.0,      0.9,      0.0   !Difb vs. E multipliers

result of these specifications is that for fast ions with 
*lab frame* energies of less than 40000.0 eV, the full
anomalous diffusivity is seen (FDIFBE(1)=1.0).  For ions
with energies between 40000.0 and 60000.0 eV, a multiplier
linearly interpolated between 1.0 and 0.9 is applied to 
yield the applicable anomalous diffusivity.  For ions 
with energies between 60000.0 and 70000.0 eV, a multiplier
linearly interpolated between 0.9 and 0.0 is applied to 
yield the applicable anomalous diffusivity.  For ions 
with energies greater than 70000.0 eV, the anomalous
diffusivity is zero (FDIFBE(3)=0.0).

6 FPP_implementation
[note by DMC May 28, 1992]

The FPP code now has the same full time and space varying
anomalous diffusivity controls that are available in the 
Monte Carlo code (implemented DMC Jan 1995).  This is also
available for FPP RF ions.

Exception: NMDIFB.eq.4 not implemented in FPPMOD (DMC Apr 2010).

5 Ripple_loss

Stochastic Domain Model (last update -- March 1995)
  	
	A stochastic ripple loss criterion is calculated for every ion 
at every time step (unless it is a first orbit).  The formula that 
determines whether or not a particle has been lost (the Goldston, 
White, Boozer criterion for stochastic ripple loss) is

              delta_s =(eps/(N*pi*q))^1.5 / (rho*q')

where eps=aspect ratio, N=number of coils, q is the plasma safety 
factor (number of toroidal turns/ number of poloidal turns), q'=dq/dr 
and rho is the Larmor ion radius.  The particle is lost if at the 
bounce point  delta, the TF ripple, is greater than delta_s. This is 
the same basic model as in the SNAP code, but includes collisions.
	 
        This model also calculates power loss, particle loss, and 
momentum loss from ripple and the corresponding J X B torque and 
rotational energy change of the plasma.  Use only for TFTR cases 
initially.

	Initial benchmarking of the criterion indicates that ion 
ripple losses will be approximately correct with the following:
Namelist INPUT file, <runid>TR.DAT, must include

        NRIP = 2       Turns on the model
        PRERPL = 'A'     Ripple field Ufile A.RPL in TFTR_DATA:
        EXTRPL = 'RPL'   available and valid for all TFTR runs.
          
           *** UFILE Data must take a very specific form; see
               the subtopic "Ripple Loss Ufile"

        ASRD = 2.0     Ripple threshold criterion factor for alpha 
                       particles and other fusion products
        BSRD = 0.5     Ripple threshold criterion factor for beam 
                       ions

where the factors ASRD and BSRD are used as follows:
ASRD*<TF ripple at bounce pt>/delta_s .ge.1 ==> ripple lost alpha
BSRD*<TF ripple at bounce pt>/delta_s .ge.1 ==> ripple lost beam ion

The recommended values of ASRD and BSRD were found by comparison 
with guiding center code simulations and may possibly change as 
more benchmarks are available.  These numbers are preliminary, and
are based on TRANSP runs using GOOCON=10.  See MH Redi, APS-1994 
for details.

**** OLDER MODEL ****

TRANSP has a VERY CRUDE toroidal field ripple loss "model" for fast
ions.  In the namelist, set

  NRIP=1   ! to turn model on...
  TAURIP=(loss time, seconds)  ! trapped ion loss time if NRIP=1

In this model, ALL TRAPPED IONS are lost to ripple with a loss time
of TAURIP; i.e. if N fast particles are deposited at time T0 on 
trapped orbits and they stay on trapped orbits, the population will
decay according to the formula

  Nleft = N * exp[ -(t-T0)/TAURIP ]

with the loss attributed to "ripple".

The code to implement this model is in subroutine RIPLOS.  If there
is interest in this model it would be easy to generalize RIPLOS e.g.
to support a spatially varying profile of ripple loss times.

6 Ripple_Loss_Ufile

Ripple loss Ufile (or MDS+) data must specify the ripple magnitude as

     f = B~/B = (Bmax-Bmin)/(Bmax+Bmin)

Here B refers to the toroidal magnetic field strength, at a particular
major radius and elevation; the variation considered is with respect to
toroidal angle at this location in the poloidal plane.

The Ufile can have two forms:

  (a) time invariant:  f(R,Z):
        1st coordinate: R grid in METERS, evenly spaced.
        2nd coordinate: Z grid in METERS, evenly spaced.

  (b) time dependent:  f(t,R,Z)
        1st coordinate: TIME, seconds.
        2nd coordinate: R grid in METERS, evenly spaced.
        3rd coordinate: Z grid in METERS, evenly spaced.

The (R,Z) domain should cover the region in which the core plasma
closed flux surfaces will reside, with margin to spare.

R is the major radius.
Z is the elevation; Z=0 corresponds to the vacuum vessel midplane.  

------------------------------------------
NOTE to TRANSP maintainer:  A special reader is used in TRDAT for the
ripple Ufile data and takes the natural log of the data read, so that
log(B~/B) is stored and passed from trdat to TRANSP.

The logarithm is used for improved behavior of bilinear interpolation of
the data.  Use the expression exp([ripple_data]) to recover B~/B.
------------------------------------------

5 Fishbone_loss
Note (dmc Feb 2007): new options added to this model, see end of
section.

TRANSP has a very simple "fishbone" loss model for Monte Carlo fast
ions.  It has the following controls:

  NLFBON  ! LOGICAL set to .TRUE. to enable fishbone losses

  TFSHON  ! onset time of fishbones (seconds)
  TFSHOF  ! time of last fishbone (seconds)
  FSHPER  ! fishbone period (seconds) -- time btw spikes
  FSHWID  ! duration of individual fishbone spike (seconds)

  FBEMIN  ! minimum energy of affected fast ions (eV)
  FBEMAX  ! maximum energy of affected fast ions (eV)
  FVPVMN  ! minimum abs[ Vpll/V ] of affected fast ions 
  FVPVMX  ! maximum abs[ Vpll/V ] of affected fast ions 

  FBLTIM  ! characteristic fishbone loss time for affected ions (secs)

For purposes of fishbone loss, vpll/v is taken at the last two midplane
crossings; if |vppl/v| at either of these points falls within the
range FVPVMN to FVPVMX, and if the energy is in range, the ion is
eligible for loss.

New March 2007 fishbone control options:

  nfbon_vpvopt=0 (default) use {FVPVMN,FVPVMX} as described above
    --OR--
  nfbon_vpvopt=1 (new option)
                 operate on trapped orbits for which trapping depth
                 exceeds the parameter:

  fbtrap_depth (default 0.0)

     fbtrap_depth=0.0 means "operate on all trapped orbits"
     fbtrap_depth=0.2   spares barely trapped orbits
     fbtrap_depth=0.8   would only affect the most deeply trapped orbits

     trapping depth = (Bmax(x)-Bmax(orb))/(Bmax(x)-Bmin(x))
        where x is an average flux surface location of the orbit, and
        Bmax(orb) is the maximum B seen by the orbit, i.e. the point
        of reflection for a trapped orbit

  Passing orbits are not affected with fishbone loss.

  When nfbon_vpvopt=1, {FVPVMN,FVPVMX} are ignored but all other fishbone
  controls still apply.

This feature added at request of Dr. Yuriy Baranov at JET 
DMC 5 Mar 2007

Species control: 
   nfbon_species = 3 (default)
     fishbones (if present at all) apply to all fast ion species
   nfbon_species = 1
     fishbones apply to beam ions only
   nfbon_species = 2
     fishbones apply to fusion product ions only

5 Lost_orbit_output_file

NOTE MG June 2009
  TRANSP has an option to generate an output file listing the 
  parameters of all Monte Carlo lost orbits at the time of
  loss.  Set the namelist switch

 NLBOUT_GATHER                 ! IF .TRUE. lost data will be collected for
                               ! time steps from ~ OUTTIM-AVGTIM to OUTTIM
                               ! storages will be expanded to 
                               ! for each time step
                               ! if .FALSE. data will be gathered for only one
                               ! time step from tbm1 to tbm2, where tbm1=< OUTTIM<tbm2 
		   	       ! Data will be stored in AC file <runid>.DATAnn
 default  is NLBOUT_GATHER = .TRUE


This comment not valid any more:
NOTE DMC Apr 2007 -- this option has been DISABLED! (it is
very complicated to maintain this in context of MPI parallelization
of NUBEAM).  If you wish it restored, please contact a current
TRANSP maintainer.


5 Beam_Neutral_Density
[upgrade DMC 28 Jul 1992 -- multiple 3d fast neutral density
profiles may be output by a single run]

TRANSP outputs only limited fast neutral density data to RPLOT.
Generally, this data is flux surface averaged and summed over
all neutral beams.

However, detailed 3d information on the profile of beam neutral
density in front of selected beams (for selected energy 
fractions, i.e. full-, half-, or third- energy neutrals) may now
be obtained via the new ACFILE interface (see the topic
ACFILE_output).

In addition to setting up for ACFILE output, set the following
namelist controls:

NBSBOX = list of beam source indices ib
  ! refers to the ib'th beam in the namelist
  ! the number of profiles computed equals the number of 
  ! indices given in the list.
NBEBOX = list of beam energy fractions
  ! =1 for full energy, =2 for half energy, =3 for 1/3 energy
  ! neutrals; for non-Hydrogenic beams =1 is required.

all remaining controls apply to *all* output 3d profiles:

NDEPBOX = number of neutral tracks (statistical control)
  ! separate calls to the deposition model are generated to
  ! compute each 3d neutral density profile; NDEPBOX controls
  ! the number of random tracks generated for this computation
  ! per fast ion timestep.  NOTE-- in setting up ACFILE output
  ! it is also possible to request time averaging which can
  ! greatly improve statistical accuracy of the simulation.

AND geometry specification:

The neutral density data is collected in a 3d Cartesian box 
aligned on the beam axis.  The box is characterized by three
coordinates (X,Y,L) where:

  L is the distance from beam source grid, cm (same coordinate
    as is used for specifying beam aperture distance XLBAPA and
    distance to tangency radius XLBTNA).

  X is the horizontal displacement from the beam centerline (or
    from a vertical plane containing the beam centerline).

  Y is the vertical displacement from the beam centerline.  In
    case of a beam not lying in a horizontal plane, Y is the 
    coordinate normal to X and L.

And the namelist controls for the 3d box geometry are:

XLBOX1,XLBOX2 -- L extent of box.  XLBOX2.GT.XLBOX1 required
  and XLBOX1 must be greater than XLBAPA(NBSBOX); i.e. the box
  must be position "past" the beam aperture opening into the
  tokamak vacuum vessel.
NLBOX -- number of grid points in the "L" direction.

XBOXHW -- X halfwidth of box.
NXBOX -- number of grid points spanning displacements -XBOXHW to
  +XBOXHW.

YBOXHW -- Y halfwidth of box.
NYBOX -- number of grid points spanning displacements -YBOXHW to
  +YBOXHW.

Sample settings:
================
NBSBOX=1,1,1    ! compute 3d neutrals for beam #1
NBEBOX=1,2,3    ! compute all energy components neutral densities
XBOXHW=20.0     ! X halfwidth is 20 cm
YBOXHW=40.0     ! Y halfwidth is 40 cm
XLBOX1=520.0    ! L from 520 to 2120 cm from beam source grid
XLBOX2=2120.0   !   note aperture XLBAPA(1) at approx 510 cm
NXBOX=20        ! 20 points from -XBOXHW to +XBOXHW
NYBOX=40        ! 40 points from -YBOXHW to +YBOXHW
NLBOX=200       ! 200 points from XLBOX1 to XLBOX2
NDEPBOX=200     ! 200 neutral tracks / beam code timestep
                ! generated for the 3d fast neutrals calculation.

This data can be examined with "pboxn0" program.

[rga Feb2003]
The beam neutral density which intersects a tube may be computed and
output as a transp profile.  The namelist controls for tube index i,

NBSTUBE(I) = index of beam to probe
NBETUBE(I) = energy fraction of beam (1->full, 2->half, 3->third)
RTUBE(I)   = radial position of start of tube
YTUBE(I)   = height of tube start above the midplane
XZETTUBE(I)= toroidal position of tube start in degrees (ccw is positive)
PHITUBE(I) = tube sightline azimuthal angle in degrees relative
             to the axis (positive in direction of plasama current)
THETTUBE(I)= tube sightline elevation angle in degrees

LMIDTUBE   = 0-> tube origin relative to tube start
             1-> tube origin relative to beam intersection (use
                 this when CX eflux is used)
             Data is collected from XL1TUBE to XL2TUBE relative
             to this origin.
XL1TUBE    = start of data collection relative to tube origin (cm)
XL2TUBE    = end of data collection relative to tube origin (cm)
NSEGTUBE   = number of data collection segments, the size of a
             segment is (xl2tube-xl1tube)/nsegtube
RHOTUBE    = radius of the tube (cm), the smaller the tube the more 
             trajectories which are required to get a decent density
             statistic
NDEPTUBE   = scales the number of trajectories used to compute the
             neutral density.  The actual number attempted is also
             a function of the tube radius.

tube transp outputs,
 TUBE0_<i> = beam neutral density for tube number <i>

5 Energy_Limited_Fast_Ion_Density
[new DMC 8 Jul 1992]

Additional profiles of fast ion density vs. radius (or other
flux surface label) may now be output by TRANSP.  These are
profiles that are constrained by energy limits.

To generate this output, set the namelist control ERNGFI to a
list of up to 5 energies, eV, in strict ascending order.  For
example, set:

    ERNGFI = 10000.0, 30000.0, 100000.0

to get energy constrained fast ion density profiles in the range

    10000.0 to 30000.0 eV       (range no. 1)
    30000.0 to 100000.0 eV      (range no. 2)
    100000.0 eV to infinite eV  (range no. 3)

In other words, the density profile associated with range no. 2
is the density of fast ions with energies in the range 30 KeV 
to 100 KeV.  **ENERGIES ARE EVALUATED IN THE LAB FRAME**.

When this option is taken, the following RPLOT output multigraphs
will be created if the indicated species exist:

     NBI_H  -- energy constrained H beam fast ion 
               density profiles.
     NBI_D  -- energy constrained D beam fast ion 
               density profiles.
     NBI_T  -- energy constrained T beam fast ion 
               density profiles.
     NBI_3  -- energy constrained He3 beam fast ion 
               density profiles.
     NBI_4  -- energy constrained He4 beam fast ion 
               density profiles.
     NFI_T  -- energy constrained T fusion product fast ion 
               density profiles.
     NFI_3  -- energy constrained He3 fusion product fast ion 
               density profiles.
     NFI_4  -- energy constrained He4 fusion product fast ion 
               density profiles.
5 Finite Larmor Radius Effects
The point at which the fast ions in the Monte Carlo code interact
with the plasma relative to the guiding center is controlled through
the namelist parameter NLBFLR.  Set,
  NLBFLR=.FALSE. to force plasma interactions at the guiding center
  NLBFLR=.TRUE. (default) to force plasma interactions on the gyro

An option to the FLR model (March 2001) allows control on how the
gyro position is found when NLBFLR=.TRUE., 
  NLBGFLR=.FALSE. (default) This is the original model which displaces
          the ion from the guiding center by one larmor radius based on
          the magnetic field at the guiding center.

  NLBGFLR=.TRUE.  The point at which an instantaneous larmor displacement
          takes the particle back to the guiding center is found and
          used as the the gyro point.  This option is appropriate when
          the larmor radius is not small compared to the scale length
          of changes in the magnetic field.

The new NLBGFLR=.TRUE. option requires a search algorithm for the 
gyro point which can impose a severe runtime penalty.  An additional 
option is available to avoid this search for ions with small 
larmor radii,
  GFLR_MIN   Particles with larmor radii less then this distance
             (in cm) will use the guiding center displacement
             as opposed to searching for the gyro point 
             when NLBGFLR=.TRUE.  The default is zero.

Additional information on the upgraded FLR model can be found in the
latex file flr.tex.
4 Fusion_products
(DMC Oct 1990)
The TRANSP Monte Carlo model may now model up to 3 fast ion species.
A typical choice might be a mix of D and T beams and He4 (alpha)
fusion product fast ions.

To set the species of the ij'th beam, set
  ABEAMA(ij) = atomic weight of species (e.g 3.0 for Tritium)
  XZBEAMA(ij) = charge of beam species

To model fusion products there are two choices:
  (a) set NALPHA=1 for a fast, non-Monte Carlo model by D. Mikkelsen.
      this model has no orbit effects and assumes instant equilibration
      of the alpha slowing down distribution on the background plasma.
  (b) leaving NALPHA=0 set NLFHE4=.TRUE. to turn on the Monte Carlo
      fast He4 model.  Set NPTCLF=[# of Monte Carlo Particles] to 
      control the Monte Carlo census of model fusion ions.  The
      default is NPTCLF=1000.  Set PLFHE4=[theshold power level, watts]
      to specify the fusion ion source power for which full Monte
      Carlo statistics of NPTCLF particles is deployed.  If the
      actual source power is greater, NPTCLF M.C. model ions are
      maintained.  If f = [actual power]/PLFHE4 is less than one,
      a population of f*NPTCLF Monte Carlo particles is maintained.
      PLFHE4 defaults to 10000 watts.

      For normal use, just set NLFHE4=.TRUE.

  (c) set NLFST=.TRUE. to model slowing down of D-D fusion Tritons
      PLFST = power threshold.

  (d) set NLFHE3=.TRUE. to model D-D fusion He3 ions slowing down.
      PLFHE3 = power threshold.

  (e) (new March 1994 by John Schivell):  set NLFSP=.TRUE. to model
      slowing down of D-D fusion Protons; PLFSP = power threshold.
      *caution* this model is still being worked on.  There are
      signs of numerical problems in the orbit integrator when
      dealing with 3 MeV protons; also, the collision operator
      may not be valid for this energy regime; work is in progress.

As of Feb 1995, the Monte Carlo model features include
  * orbit effects, orbit loss, thermalization source.
  * collisional heating of the background plasma.
  * time dependent evolution of the slowing down population.
  * nuclear burnup of D-D Tritons or He3.
Set namelist control NLFATOM=.TRUE. to get
  * atomic physics effects of/on the fusion product ions (e.g. charge
    exchange loss of fusion product fast ions)
optional (done if the appropriate thermal specie is provided):
  * accumulation of slowed down "ash" thermal ions in the background
    plasma.
model limitation:
  * fusion ion source function is isotropic and monoenergetic in the
    plasma reference frame.
effect not included:
  * collisional coupling between fast ion populations of different
    species.
5 General_comment
Monte Carlo modeling of fusion product ions uses largely the same
code as that used for beam slowing down.  Generally, features
available for beam ions (e.g. ripple loss, anomalous diffusion)
are also available for fusion product ions.  In this help file,
many of these features are described under the neutral_beams
subtopic of "namelist".

5 Source_Function
[new DMC 8 Jul 1992]
An option has been added to give TRANSP the ability to use time 
dependent data to control the magnitude of fusion product ion
sources.  The time dependent data takes the form of a 1d Ufile
vs. time only.  The source profile shape is taken from the 
simulation; the total magnitude is renormalized to match the
input data.

For alphas, set

    NLUSFA=.TRUE.

and in the TRDAT namelist set

    PRESFA='xxx'  ! SFA data Ufile prefix
    EXTSFA='yyy'  ! SFA data Ufile suffix

to specify the alpha source magnitude data.

For DD fusion product tritons, set

    NLUSFT=.TRUE.

and in the TRDAT namelist set

    PRESFT='xxx'  ! SFT data Ufile prefix
    EXTSFT='yyy'  ! SFT data Ufile suffix

to specify the triton source magnitude data.

For DD fusion product protons, set

    NLUSFP=.TRUE.

and in the TRDAT namelist set

    PRESFP='xxx'  ! SFP data Ufile prefix
    EXTSFP='yyy'  ! SFP data Ufile suffix

to specify the proton source magnitude data.

NOTE:  NLUSFP and NLUSFT cannot BOTH be TRUE, since these both
specify the magnitude of the same DD fusion reaction.  The
controls are kept separate at this time to allow eventual
support for D-He3 protons in the fusion product model.

For DD fusion product He3, set

    NLUSF3=.TRUE.

and in the TRDAT namelist set

    PRESF3='xxx'  ! SF3 data Ufile prefix
    EXTSF3='yyy'  ! SF3 data Ufile suffix

to specify the He3 source magnitude data.

One may also set PRExxx/EXTxxx inputs while leaving NLUxxx=.FALSE.
This causes the Ufile data to be passed to RPLOT for comparison
but the fusion product source magnitude is controlled by the
TRANSP simulation (i.e. *not* renormalized to the input data).
5 Cris_Barnes_comment_re_burnup_calculation
From:	RAX::CBARNES  "Cris W. Barnes" 22-OCT-1991 23:20:25.84
To:	transp,strachan,jmccauley,zarnstorff,CBARNES
CC:	CBARNES
Subj:	BURNIT/TRANSP comparison, shot 55806

FYI:
 Doug re-ran TRANSP TFTR.90 55806A11 as 55806A13 with triton 
burnup.  Time-integrating from 2.5 to 4.5 seconds in RPLOT the
MNEUT (measured 2.5 MeV neutrons), the FBNTS (burnup on beam 
deuterons) and the FTNTS (burnup on thermal deuterons) gave 
yields of 2.77e16, 1.06e14 and 3.05e14 respectively, for a 
triton burnup of 4.11e14/2.77e16 = 1.48%.

My first simulation of 55806 used my kludged Zeff and Ti(0), 
and gave a burnup of 1.59%.  I used the exact ZEFFM (the Zeff)
and the TI0 [Ti(0)] from TRANSP and re-ran BURNIT and got 1.42%
(see the latest UFILES in nf_all:, for example nf_all:b55806.n14).  

The 12% difference in the BURNIT calculation from using a different
Zeff(time) is typical of the uncertainties that come from the Zeff.
The 4% difference between TRANSP and BURNIT is very modest and well
within the 5% uncertainties I claim by calculational effects.

Doug's previous message claimed 4% orbit + scattered losses, 
compared to my 2% calculated first orbit losses only.  This is 
hard to compare, but seems sufficient agreement for the confined
fraction.  Note that as an estimate of the converse problem, the
prompt losses, the agreement is only within a factor of 2!

I will pursue a comparison of 37065 when time permits.  I will 
identify one of the three TRANSP runs as being suitable, create
a BURNIT run using the same inputs as that TRANSP run, compare
that BURNIT run to the case documented in Batistoni and Barnes 
(1991), and then have Doug re-run the TRANSP case.  
   ---Cris

4 ICRF_heating
The TRANSP ICRF model consists of Greg Hammett's bounce-averaged
Fokker-Planck code, FPP, coupled to a number of user selectable
ICRF full wave deposition codes.  For additional information on 
FPP and on the original RF code (Dave Smithe Spruce), see the text
documents trfpp.doc and fpp.doc (in source/fppdoc).

The model is activated by setting

  NLICRF=.TRUE.

To select the RF wave deposition model, choose

  NICRF=1 ... for new (Belgian) Spruce code (see subtopic)
  NICRF=5 ... for original Dave Smithe Spruce code
  NICRF=6 ... TORIC-3 (Brambilla et al)

Caution:  the following model installations are new, still being
          debugged, robust performance not demonstrated as of 12/2005

  NICRF=8 ... TORIC-4/5 (Brambilla et al., newer version - full numerical
              MHD equilibrium representation)
  NICRF=9 ... TORIC-4/5 -- same as NICRF=8, but with reduced resolution
              allowed, at user's own risk!


dmc Jun 1997:  multiple antenna, multiple frequency operation
is now supported.  Set

  NICHA = <number of antennae>

and then set the controls for each antenna as described in the
subtopics.

dmc Feb 1996:  the maximum energy of the energy grid for the 
  Fokker Planck slowing down calculation of the RF tail species
  can now be set (previously it was hardwired at 10 MeV):

     ERFMAX=<max grid energy, eV>

  the default top energy value is still 10 MeV.

  Caution -- due to fusion cross section table limits, the
  maximum allowed value of ERFMAX is 20 MeV, i.e. 2.0e7 eV.
5 On_and_Off_Times
The usual best approach is to use input power data to set the
ICRF on and off times.  

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

If time dependent input power data is not available, the on/off
times can be set by the global controls, or they may be set
separately for each antenna.

The global controls are:

  TCRFON  ... ICRF on time (secs)
  TCRFOF  ... ICRF off time (secs).

which then become the on and off times for all antennae.  The
global controls are used only if the antenna by antenna controls
are not present in the namelist.

To set the on/off times separately for each antenna, set

  TonIcha(j) = on time for jth antenna
  ToffIcha(j)= off time for jth antenna.

j running from 1 to NICHA = the number of antennae.  CAUTION:
if TonIcha/ToffIcha is set explicitly for one antenna, it must
be set explicitly for all antennae!

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

It is usually best, by far, to use Ufile input data to give
the ICRF antenna power as a function of time, for each antenna.
This is the 2d "RFP" Ufile vs. time and antenna index.  If RFP
data is given, the code default is to use it to infer the on
and off times.

The algorithm for setting the ICRF on/off times can fail if the
power data does not got to zero cleanly before/after the ICRF 
heating pulse.  To override the resetting of TCRFON and TCRFOF
from data, one can set 

  NLRFTFIX=.FALSE.

in the namelist, and then give the correct namelist on and off 
times described above.  Or, better, one can use the following
controls to modify the operation of the on/off detection 
algorithm:

dmc Nov 1994:  the automatic on/off time detector has been
enhanced with additional controls:
 if NLRFTFIX is true:
     PRFTFIX  -- threshold power (watts if positive, -fraction
                 if negative) used to define on/off times *for
                 each antenna* from input power vs. time for
                 that antenna.  The default is -0.05, i.e. 
                 threshold is 5% of the maximum power (see
                 note).
     DTRFTFIX -- time to back off from threshold power times,
                 looking for actual zeroes in the input power.
                 default:  0.01 seconds.

note:  for each antenna, the "maximum power" is defined as the
  maximum of (the maximum power occurring at any time on the
  antenna) and 1/NICHA * (the maximum total ICRF power summed
  over all antennae).  This algorithm prevents a 5% threshold 
  from resulting in spurious on/off time detection on antennae
  for which there is in reality never any input power.
5 Vacuum_Vessel
Some RF codes use a "perfectly conducting" vacuum vessel as a
reflecting boundary for the wave field.  So, to use the ICRF
model, the user needs to give the vacuum vessel shape.  These
are given in the arrays VVRMOM and VVZMOM:

  R(th) = Sum: VVRMOM(i) * cos((i-1)*th)
  Z(th) = Sum: VVZMOM(i) * sin((i-1)*th)

where up to 8 moments can be given, counting the zero'th moments
given in VVRMOM(1) and VVZMOM(1).

Additional notes from the rf/fpp documentation:

For comparison, the Lao-Hirschman 2-moment representation is of
the form:

R(th) = R0    + a cos(th) + R2 cos(2 th)
Z(th) =     E ( a sin(th) - R2 sin(2 th) )

Describing the VV shape with the 4 parameters Rmin, Rmax,
Rtop, and Ztop (these last two give the position of the top of
the VV) we can calculate the Lao-Hirschman coefficients via:

a  = (Rmax-Rmin)/2
Rx = (Rmax+Rmin)/2

The next two equations can be solved by combining them together
to make a cubic equation.  Or for small d they can be solved
iteratively by using R2=0.0 as an initial guess:

d  = (Rx-R2-Rtop)/a   ! a measure of "D-ness" or triangularity
R2 = 3 a d / (9 - 8 d**2)

Once the above two equations are solved, we can then find:

R0 = Rx-R2
E  = 3 (Ztop/a) (9 - 8 d**2) / (9 - 4 d**2)**(3/2)

5 Grid_Resolution
RF wave deposition codes support a variable grid, for the 
following reasons:

  *  if the grid is too coarse, the wave solution is rubbish
  *  if the grid is too fine, cpu hours are needed for each
     timestep
  *  the proper grid choice varies depending on plasma and
     RF antenna configuration

It would be desirable if an "adaptive" grid algorithm could
be employed.  For now, however, the following is available,
for the SPRUCE wave code variants:

  NichPsi -- number of radial grid points (default 128).
  NichChi -- number of poloidal grid points (default 64).

[caution -- as of June 1997 the "old Spruce", NICRF=5, still
uses a hardwired grid].

For TORIC (NICRF=6,7,8), which uses a Fourier representation in the
poloidal dimension, the poloidal resolution is set by specifying
the number of poloidal modes:  NMDTORIC (default=15).  THIS IS NOT
NECESSARILY ENOUGH TO RESOLVE THE WAVE PHYSICS on the other hand it
is very expensive to run larger numbers of modes.

For NICRF=7,8:  The minimum allowed valude of NMDTORIC is 31.  It is 
recommended to set NICHCHI to a value equal to 2*(NMDTORIC+1), which
should be a power of 2, i.e. one of the following combinations:

  NMDTORIC   NICHCHI

    15         32       NICRF=6 or NICRF=9
    31         64       NICRF=6,8,9
    63        128       NICRF=6,8,9

Caution-- in a recent test on an Opteron workstation, going from
32 to 63 modes caused the runtime to increase by a factor of 6,
from 1 minute 40 seconds to about 10 minues, for a CMOD test case.

Also, for NICRF=8,9:  NICHCHI=2**N and NMDTORIC=NICHCHI/2 - 1 are
both required!  (A future version may relax this requirement).  The
TRANSP namelist checking logic will enforce this by promoting NMDTORIC
to a higher value if necessary.

5 Frequencies_et_al
The RF code supports multi-frequency operation.  If multiple
antennae inject waves of different frequencies, these are
evaluated independently in a loop, and the heating profiles
are summed.  

In addition, each antenna is characterized by an "Nphi spectrum"
which specifies the Nphi values of the injected waves (see the
subtopic...).

The relevant controls are:

  NichA  -- number of antennae

The following can (and perhaps should) be provided as Ufile data,
but can be specified in the namelist if no such data is available:

  FRQicha(1...NichA) -- frequency on each antenna (Hz)
  PRFicha(1...NichA) -- power on each antenna (Watts)

  Tonicha(1...NichA) -- Time On of each antenna (Seconds)
  Tofficha(1...NichA) -- Time Off of each antenna (Seconds).

Antenna powers are usually given as the RFP Ufile, a 2d Ufile
vs. time and antenna index (1d if there is only one antenna).  
The trace versus time on the first index gives the power trance
for antenna #1, and so on for the other antennae - indices.  
Usually, the on/off times are computed from this data rather 
than being given explicitly -- see the subtopic on on/off times. 

New 23 Oct 1997 -- RF frequencies vs. time now also be given
by Ufile input.  Use the RFF Ufile, a 2d Ufile vs. time
and antenna index; 1d Ufile if there is only 1 antenna.

6 Nphi_spectrum
The Nphi spectrum should be specified separately for each antenna.
(This method of specification replaces the old controls WIDICHA,
SEPICHA, PHICHA, which in any case only worked for one antenna and
did not allow the Nphi spectrum to vary from antenna to antenna):

Note that each distinct Nphi value requires a separate call to 
the ICRF wave code, so, large Nphi spectra are computationally 
expensive!  Therefore, historically, most TRANSP runs have used 
a "single representative Nphi" representation of the wavefield,
i.e. only one Nphi value per antenna has been used in many runs.

Note also: the old Wave Codes, SPRUCE & DSPRUCE (NICRF=1 and
NICRF=5) both require MSYM_NPHI=1 for all antennae.  In
other words, only TORIC supports the asymmetric Nphi spectrum!
It is also recommended to use TORIC only, if the number of Nphi
values per antenna is greater than 1.

Note#2 -- Jan 2009 (dmc) -- the Nphi spectrum power is now adjusted
according to the plasma response; new RPLOT outputs are provided to
examine the results.  See the end of this topic... This is only an
issue if more than 1 Nphi per antenna is employed.

Note#3 -- As of Jan 2009 TRANSP still uses a very old FPP code whose
RF operator treats the Nphi spectrum in a symmetrized form.  The
consequences of this assumption for model accuracy is unknown.  We
plan to replace this FPP code with a better validated model (CQL3D)
as soon as we are able.

Let j = the antenna number.

  MSYM_NPHI(j) = 1    ! INTEGER flag -- 1 if Nphi spectrum is 
                      !  symmetric, i.e. +/-Nphi wave is present
                      !  for each Nphi value given.  IC fast wave 
                      !  driven current set to zero.
                      !    default: 1

  NUM_NPHI(j) = <no. of Nphi values to be given, max 20>
                      ! number of distinct Nphi values to be given.
                      ! if left to zero, use the old symmetric single 
                      ! value Nphi estimate based on antenna phasing 
                      ! info (PHICHA -- a rough guess!)
                      !    default: 0 value

Let k = NUM_NPHI(j).

  NNPHI(1:k,j) = <Nphi values>
                      ! must be in strict ascending order;
                      ! if MSYM_NPHI(j) is 1 (symmetric spectrum)
                      ! then this value  must be >0

  WNPHI(1:k,j) = <Vacuum Nphi power weightings>
                      ! fraction of antenna power to be attributed to 
                      ! each Nphi value.  The code will normalize
                      ! these weightings so that the total power
                      ! is correct, equal to PRFICHA(j) or the
                      ! time interpolated Ufile value.
                      !   Default: equal weight to all Nphi values.

(New DMC Jan 2009)
RF physicists have educated me that the plasma response varies with
Nphi and must be taken into account, in figuring the net power coupling
vs. Nphi.

This has now been done.  So, unless the namelist variable
NLIC_VAC_SPEC (default .FALSE.) is set .TRUE., the ICRF coupled power 
distribution amongst the Nphi's are adjusted to be proportional to

   R(Nphi)*[Vacuum Nphi power weighting]

Where R is the plasma load or coupling factor (watts of absorbed power
per current at antenna **2, e.g. MW/kA**2) computed by such codes as
TORIC.  

If NLIC_VAC_SPEC=.TRUE. the vacuum power spectrum is coupled as given,
which recaptures the behavior of the earlier version of the code.

The total coupled power is still presumed to match the input total 
antenna power that was specified.  The following RPLOT outputs are 
available to examine Nphi spectra:

  SPNPHI1 -- Vacuum vs. coupled Nphi power spectrum, antenna #1
  SPNPHI2 -- Vacuum vs. coupled Nphi power spectrum, antenna #2
  SPNPHI3 -- Vacuum vs. coupled Nphi power spectrum, antenna #3
    --etc--

The above spectra are in dimensionless units -- power fractions.

The total power, summed over all antennas, vs. (Nphi,t), can be
plotted in the profile function PIC_NPHI.  This is given in Watts.

5 Antenna_Geometry

"Traditional" specification requires all antennas to have the same
geometry.

"New" specification allows a different geometry for each antenna.

If for any antenna the new specification is defaulted (i.e. by 
specifying no data points), then the traditional specification is 
used for that antenna.

6 Traditional
These specifications define the geometry for all antennas for
which the "new" specification method is not used.

The antenna shape can be specified in two ways:

(1)  Set

   NGEOANT =1       ! signal use of RMJICHA/RMNICHA/THICHA
   RMJICHA = "major radius" of antennae (cm)
   RMNICHA = "minor radius" of antennae (cm) 
   THICHA  = "poloidal angle extent" of antennae (degrees)

with interpretation:

   1.  antenna is centered on midplane (Y=0)
   2.  major radius location of center of antenna is
         RMJICHA+RMNICHA
   3.  extension of antenna above/below the midplane is
         RMNICHA*sin(THICHA/2)
   4.  if RMNICHA.gt.0  the antenna is on the low field side
       of the plasma, and the antenna is curved with curvature
       equal to that of a circle of radius RMNICHA.
   5.  if RMNICHA.lt.0  the antenna is on the high field side
       of the plasma, and the antenna is *not* curved.

(2)  Give the antenna geometry explicitly as a sequence of (R,Y)
     pairs:

   NGEOANT = <a number between 2 and 40>
   (RGEOANT(i),YGEOANT(i)), i varying from 1 to NGEOANT:
      an ordered (R,Y) pair sequence that describes the antenna shape.

Also: some codes want the distance from the antenna face to the faraday
shield.  This is given by RFARTR in cm; default = 2.0 (cm).  Not all
wave codes make use of this information.

6 New

Optionally, the geometry may be specified separately for each 
antenna.  For antenna j this is requested by giving a positive 
RGEOANT_A values to the ordered sequences of pairs {RGEOANT_A,
YGEOANT_A}:

   RGEOANT_A(i,<antenna_no>),YGEOANT_A(i,<antenna_no>)), i varying 
   from 1 to NGEOANT_A(<antenna_no>), an ordered (R,Y) pair sequence
   that describes the antenna shape.

   Note: NGEOANT_A(<antenna_no>) = <a number between 2 and 40> is
   inferred from the number of consecutive POSITIVE values of
   RGEOANT_A(:,<antenna_no>) starting at RGEOANT_A(1,<antenna_no>).

   *** NGEOANT_A is not a namelist variable ***

Also:
   RFARTR_A(<antenna_no>) can be used to separately specify the 
   distance from the antenna to the Faraday Shield (cm) for the
   specified antenna number.  If defaulted, RFARTR is used for
   all antennae.  Not all wave codes make use of this information.

5 Minority_Specie
The RF models can heat multiple fast ion species:  "thermal"
majority, injected resonant beam ions, resonant fusion product ions,
or a "super-thermal" minority.

If minority species are desired, set:

  XZMINI(...) = Z of minorities
  AMINI(...)  = A of minorities
  FRACMINI(...) = fraction of minority density to attribute to
                  each specie

  The number of minorities are determined by the number of non-
  zero values of the XZMINI and AMINI arrays.

  The total minority ion density (RHMIN) is input, as described
  in what follows.  The density for a particular minority specie
  IG is FRACMINI(ig)*RHMIN.  The species sum of FRACMINI will be
  normalized to unity at startup.

  FRMINI = density fraction ( << 1 ).  n-minority = FRMINI * ne.
       or
    use 1d Ufile FMN to make the minority fraction a function of time
       or
    use profile Ufile NMR to give the minority density evolution 
    explicitly.  NOTE that the minority density given is the SUM
    of the densities of all the minority species, and that there
    is no independent control of the individual minority specie 
    densities at this time (dmc Oct 1997).
  TAUMIN = minority specie ptcl & energy confinement time -- used 
    to set the minority carried losses, when the minority specie is
    thermal (i.e. not yet heated or thermalized after end of RF
    heating).

Restriction:  If a given isotope (say He3) is an RF minority,
it cannot simultaneously be given as a beam or thermal ions
specie.  The model only allows one brand of He3 per run.

Each minority specie uses up a TRANSP fast ion slot.  As of Oct 1997
TRANSP has five fast ion slots.

5 Current_drive
DMC 1-Jan-2011: TORIC bug of prior versions has been fixed; TORIC IC 
driven current is available.

The modern version of TORIC (nicrf=8 or 9) can compute current drive.
This is current driven directly by the wavefield (i.e. not indirectly
through a minority or resonant species).  This can be computed for
antennas from which a non-symmetric n_phi spectrum is launched--
that is, for antenna #iant, MSYM_NPHI(IANT)=0 in the namelist. A
neighboring section describes the controls (NUM_NPHI, NNPHI, WNPHI)
for defining the antenna wave n_phi launch spectrum, for each
antenna.

Please note that for antennas IANT with symmetric n_phi spectrum, 
MSYM_NPHI(IANT)=1, which is the default, the driven current is 
hardwired to ZERO.

The TORIC RF current drive model may not be appropriate in all
situations.  To have TRANSP use the TORIC computed current drive,
verify that 

  NMOD_ICRF_CUR = 1  ! activate ICRF current drive

The default value is (1), but, some namelists may have set this to
zero.

The current predicted by TORIC can be scaled by the namelist anomaly
factor XANOM_CURIC (its default value is 1.000).  So for example, to
have TRANSP use 1/10 the current predicted by TORIC one would set

  XANOM_CURIC = 0.1  ! apply anomolous factor...

SUMMARY: to get ICRF driven current from TORIC: (a) use non-symmetric
launch spectrum, MSYM_NPHI(...)=0; (b) verify activation of the IC driven
current model, NMOD_ICRF_CUR=1; (c) optionally, scale the model results
with XANOM_CURIC.

5 TORIC_model_options
The following controls are available for NICRF=6,8,9:
TORIC options (copied from freeshare/port.for):

C  TORIC ICRF code specific control switches as per Dan Clark
C--------------------------------------------------
C   TORIC ICRF PACKAGE UNIQUE CONTROLS: BEGIN
C
CP I   NMDTORIC       */15/ Number of (TORIC) poloidal modes
C
CP D   RFARTR         */2.0D0/ distance from antenna to Faraday shield (cm)
CP DA  RFARTR_A(IICHA) */-1.0D0/ distance, antenna to Faraday shield, on
C                      per antenna basis (default: use RFARTR for all
C                      antennae).
CP D   ANTLCTR        */1.0D0/ effective antenna propagation constant
C               ANTLC > 0 current ends abruptly at feeders
C               ANTLC < 0 current goes smoothly to zero around feeders
CP I   NFLRTR         */1/ ion FLR contributions
C              = 1 included
C              = 0 ignored
C              = -1 order reduction algorithm
C                (NBPOLTR = 0 recommended if NFLRTR <= 0)
C              = -2 order reduction algorithm with automatic
C                suppression of spectral pollution
C                (equiv. to NFLRTR = -1 and no forced IBW damping)
CP I   NFLRETR        */1/ electron Finite Larmor radius contribution:
C              =  1  included (also mixed TTMP-ELD electron term)
C              =  0  ignored (only ELD)
C              = -1  1/2 TTMP without mixed term (tests only)
CP D   FLRFACTR       */1.0D0/
C                  adjustment for FLR terms in the ion current (TORIC)
CP I   NBPOLTR        */1/ poloidal magnetic field
C               = 1 included
C               = 0 ignored
CP I   NQTORTR        */1/
C                  toroidal broadening of the plasma dispersion function
C               = 1 included
C               = 0 ignored (default if NBPOLTR = 0)
CP I   NCOLLTR        */0/ collisional contribution to argument of plasma
C               dispersion function
C               = 1 included
C               = 0 ignored
CP D   ENHCOLTR       */1.0D0/ electron collision enhancement factor with NCOLL
CP DA ALFVNTR(20)         */0.0D0/ ad hoc collisional broadening of Alfven and
C                   ion-ion resonances:
C                   ALFVNTR(1) included (= 1.0) or ignored (= 0.0)
C                   ALFVNTR(2) enhancement factor (~ 0.1)
C                   ALFVNTR(3) value of ABS((n//^2 - S)/R) below which
C                              damping added (~ 10.0)
C                   ALFVNTR(4) value of ABS(w/(k//*v_te)) below which
C                              damping calculated -- needed to maintain
C                              reasonable values of RF current (~ 5.0)
C
C   TORIC ICRF PACKAGE UNIQUE CONTROLS: END

5 MPI_TORIC

Set NTORIC_PSERVE = 1 to request use of MPI-enabled TORIC.  Another
section of TRANSP HELP discusses parallel components generally
(search for "NTORIC_PSERVE").

5 All_Fast_Ions
The RF deposition codes will evaluate heating profiles for all
species with fundamental or 2nd harmonic resonances in the plasma;
some wave codes allow evaluation of high harmonic fast wave (HHFW)
damping as well.

(DMC Oct 2007): theoretical research is under way to provide means of
self-consistent evaluation of RF wave damping and plasma response.
This will entail development of numerical descriptions of non-Maxwellian
fast ion distributions which will then need to be used by the wave code
to compute the correct damping.

At present, however, only the lowest order moments (density, average 
energy) are taken from the fast ion distribution functions for use by 
the wave codes.  RF experts say that such an approach will not be
capable of capturing the correct wave-plasma interaction.

Nevertheless, modeling options are provided to "force" a plasma response
with the correct power coupling as prescribed by the RF wave code with 
its simplified damping calculation using a pseudo-Maxwellian fast ion
target.

TRANSP has 3 kinds of fast ion species:

  RF minority
  modeled by FPPMOD:  continuum Fokker Planck code: collision operator,
      quasi-linear ICRF operator, toroidal electric field operator.

  Beam ions
  modeled by NUBEAM:  Monte Carlo; RF operator now available
     set NLFI_MCRF = .TRUE. to activate RF operator

  Fusion product ions
  modeled by NUBEAM:  Monte Carlo; RF operator now available
     set NLFI_MCRF = .TRUE. to activate RF operator

For NUBEAM species, the MCRF operator will only be used on those fast
species which are estimated by the wave code to damp 5% or more of the 
ICRF antenna power.

Only the newer versions of the TORIC wave code (NICRF=8,9) can be used
if NLFI_MCRF=.TRUE. is set.

All species AMU will be normalized to proton mass, for details see (5) Plasma.

5 Model_Options
Although various modeling options are provided, it is not guaranteed 
that every RF code will implement them.  The standard options are:

  NLICHISO  (logical)  .TRUE.  to force isotropy, Tperp=Tpll, in the
      RF code's view of fast ion distributions.

  NLICHPOS  (logical)  .TRUE.  to "try hard" to make RF heating
      profiles positive everywhere for all species.

  NICHTNSR  (integer)  1 for full dielectric tensor
                       0 for reduced order tensor.

NICRF=1 (new Spruce) supports all of the above.
NICRF=5 (old Spruce) supports NLICHPOS; NLICHISO it treats as always TRUE;
                     NICHTNSR it ignores.

NICRF=6,8,9 (TORIC options) DO NOT USE these model options; see
the TORIC namelist for TORIC options.

There is also an option to deal with current TRANSP limitations:

  NLICMCTH  (logical)  .TRUE. to deposit ICRF heating of 
                  Monte Carlo fast ion species directly 
                  to thermal ions

which will default TRUE as long as there continues to be no
Monte Carlo RF operator (dmc 25 Jun 1998).
5 Damping_Correction
Some RF codes offer a damping correction, designed to compensate
somewhat for imperfections in the ordering approximations in the
RF dielectric tensor.  

The correction works by examining the discrepancy in RF power 
"Pqlo" seen by the Fokker Planck code's quasi-linear RF operator 
(based on application of the wave fields to the full fast 
ion distribution) compared with the power "Pwave" seen by the RF 
code (using an approximate fast ion distribution based on Tperp 
and Tpll).  If, locally, Pqlo/Pwave .gt. 1, a damping adjustment
is calculated which, *on the next step*, will reduce the apparent
density of the fast ion specie to the wave deposition code.  This
is done iteratively and tends to bring the power profiles Pqlo and
Pwave into allignment.

The following controls constrain the adjustment range:

   QSLDMIN (default 0.2) the minimum allowed damping factor
   QSLDMAX (default 1.0) the maximum allowed damping factor.

At present, only the "Old Spruce" RF wave package (NICRF=5)
supports this feature.

5 1995_Belgian_Upgrade
[This note is about the code accessed via NICRF=1].

There is a new version of the ICRF wave propagation code SPRUCE,
which has been developed by Michel Evrard, Jef Ongena, and 
D. Van Eester of the Laboratoire de Physique des plasmas in Belgium.
One of its main improvements is that it's dielectric tensor employs
the full Bessel functions.  This avoids the small kperp*rho 
expansions of the previous method, which broke down for energetic
alpha particles and for the energetic minority tail.  [The energetic
species is still treated as a hot Maxwellian.  Separate values of 
Tperp and Tpar are allowed, though we've forced isotropy for now,
as they would like to do some more testing.]  An order-reduction
method is still used, and a nonlinear root finder is used to find
the fast-wave root.

Papers which use the SPRUCE RF package in TRANSP should cite:

Michel Evrard, Jef Ongena, and D. Van Eester,
"Improved dielectric tensor in the ICRF module of TRANSP", 
in AIP Conference Proceedings #?, Radio-Frequency Power in Plasmas,
14th topical conference, Palm Springs (1995) 
(to be published by AIP, 1995).

5 Anomalous Diffusion
The Anomalous Diffusion option that has existed for Monte Carlo
beam ions is now available for FPP RF ions as well.  For a 
detailed description of the controls see the section on neutral
beams; the same controls are used for RF ions.

Note -- DMC 28 Oct 2004 -- anomalous radial diffusion is currently
disabled in the RF model.

5 ICRF_Sawtooth
[DMC 16 Aug 1994]
A sawtooth mixing model is now available for ICRF minority
fast ions.  The NLSAWIC switch (default .TRUE.) controls
whether this model is on.

NLSAWIC=.TRUE. only has effect if also

    NLSAW=.TRUE.  ! bulk plasma sawtooth model is "on"
   NLICRF=.TRUE.  ! ICRF heating is "on"

The code was developed by Rick Goldfinger at ORNL.  Here are
his comments:

An ICRF minority ion sawtooth model has been implemented in
TRANSP (subroutine sawfppic).  The model works in conjunction
with the ICRF wave and Fokker Planck codes developed by 
Greg Hammett, Dave Smithe, and Pat Colestock.  The model
replaces the minority ion distribution function with its
volume averaged value from the magnetic axis to the mixing
radius; outside this radius the distribution function is 
unchanged.  This is done at each sawtooth event when there
is a non-thermal minority ion distribution; it does not
work before the ICRF turns on , or after the minority ions
have thermalized.  Energy moments of the modified distribution
function show this flattening; the minority particle density
is NOT affected by this model because TRANSP legislates the
minority density as determined by input quantities (see
TRANSP OPERATIONS NAMELIST MINORITY_ION_DENSITY).  It is up
to the user to model the minority density as desired.

5 Quasilinear_Operator_Renormalization
In the course of an ICRF Fokker Planck simulation, the effect
of the RF on the minority fast ion distribution is described
by a set of "quasilinear diffusion coefficients" known
collectively as the quasilinear operator (QLO).  The 
description of how to derive the QLO and apply it to the
Fokker Planck equation is described in Greg Hammett's 1986
PhD thesis, "Fast Ion Studies of Ion Cyclotron Heating in
the PLT Tokamak".

The ICRF wave code specifies both the damping power density 
on minority fast ions, and the 2-dimensional wave field
(Eplus, polarization, Kperp, Kpll).  In theory, the QLO 
coefficients are fully determined by the wave field alone.

In practice, however, because of differences in the 
representation of the fast ion distribution between the
Fokker Planck model and the wave code, the damping power
implied by the QLO from the wave field alone will in 
general *not* match the damping power expected by the
wave code, and the integrated profile will not match
the power-at-the-antenna that was specified to the 
wave code.

Therefore, the fppmod package includes a procedure for
"renormalization" of the QLO to try to match the wave 
code power, both locally and globally.  This renormalization 
is dynamically adjusted through multiple timesteps of the FP 
equation, in order to maintain the power input found by the
wave code.

This procedure is effective for most cases, but not all.
Occasionally, the situation arises where P(QLO) -> zero
but the wave code sees high damping P(wave).  It is unsafe 
to scale up the QLO by P(wave)/P(qlo) as P(QLO) -> 0; in
practice the scaling factor S = P(wave)/P(qlo) is limited
to 2.0, with some additional upward scaling possible 
during timestepping dynamic adjustment.  Finally, if
P(QLO) << P(wave) locally, some power will be lost; the
code tries to compensate for this by scaling up the 
entire P(QLO) radial profile to make up the deficit-- but 
the global renormalization as well is not allowed to exceed
a factor of 2.0 (which is on top of the local factor).

==> There are cases where the full wave code power cannot be
    fully delivered to the Fokker Planck modeled minority 
    species.

A serious discrepancy between P(QLO) and P(wave) may indicate
an unresolved computational physics modeling problem.

See the section on RPLOT_Outputs for description of output
data which can be used to monitor the QLO renormalization.

5 RPLOT_Outputs
Upgraded dmc Jan. 2005 -- Nphi spectrum information added.
Partitioning of RF absorbed power by Nphi can now be 
obtained.  See profile multigraphs PIC*.  Also, current
drive outputs JIC* have been added but will be zero until
TORIC4 is integrated into TRANSP (dmc Jan 2005).

Upgraded by D. McCune Sept. 2003 -- profile multigraphs
SMINBA and TQMINBA added.  PMIN_QLO has been added, along
with extra terms in the RFH* multigraphs, to give extra
information on the RF Quasilinear Operator (QLO) renorm-
alization (see preceding section for discussion).

Presence of ICRF heating causes a number of RPLOT output data
items to be activated.  ICRF terms are added to a number of
multigraphs, and multigraphs are created just for the ICRF
heating data itself.  The following lists give details:

Scalar multigraphs:

  RF term added to any fast ion power balances present in the
    run (H, D, T, He3, He4 beams are possible;  He4 (alpha),
    He3, T and P (proton) fusion products are possible); the
    names are:
  beams:  PBBAL, PBBAL_H, PBBAL_D, PBBAL_T, PBBAL_3, PBBAL_4
  fusion products:  PFBAL_4, PFBAL_3, PFBAL_T, PFBAL_P

  ** caution ** Unless NLFI_MCRF=.TRUE.,
    Monte Carlo fast ion models cannot absorb the
    RF power.  The power is transferred direct to the thermal
    ion species or discarded!

  RF scalar power balance multigraph:  PRFBAL

  RF antenna powers:  PICHA

  Ratios of Wave Deposition Power to Fokker-Planck Quasi-
    linear Operator Power, for Fokker-Planck modeled
    fast ion species:  RKPRHO (QLO renormalization).

  Quasi-linear Power Adjustment Factors:  QKPRHO

Profile multigraphs:

  RFDENS -- minority ion species density profiles

  IEHEAT -- RF term PIICH added to thermal ion heating profiles
  EEHEAT -- RF term PEICH added to thermal electron heating
    profiles

  PICHANT-- total power absorbtion, vs. antenna/frequency
            summed over all absorbtion processes

  PICNF1, PICNF2, ...
         -- power absorbtion vs. Nphi for anteenna/frequency
            no.s 1,2, ...

  QRFBAL -- RF heating profile power balance

  QMINBA -- minority species profile power balance
            (ICH power is the renormalized P(QLO); see also
            PMIN_QLO for comparison of QLO and wave code
            ICH minority heating power).

  SMINBA -- RF minority profile particle balance

  TQMINBA -- RF minority profile angular momentum balance

  PMIN_QLO -- comparison of ICH power to minority species, as
            seen by the wave code, to the renormalized QLO
            P(QLO).  When the renormalization is working well,
            these curves should be nearly equal.

  Ratios of local wave deposition power to FPP quasi-
    linear operator power:  ICHRATP

  For FPPMOD species (RF minority):
    Comparision of wave deposition profile to FPP quasi-
    linear operator (QLO) power profile, *before* and *after*
    renormalization for each Fokker-Planck  modeled fast ion 
    species:
      minority ions: RFHMIN_H, RFHMIN_T, RFHMIN_3, ...

  For NUBEAM species (beams, fusion products):
      beam species:  RFHB_H, RFHB_D, RFHB_T, RFHB_3, RFHB_4
      fusion products:  RFHF_4, RFHF_3, RFHF_T, RFHF_P
    Comparison of wave code computed power deposition profile
    with the plasma response power estimated by the Monte Carlo
    code (QLO, Quasi-Linear Monte Carlo Operator).

dmc -- 21 Sep 1998
updated 3 Sep 2003
updated 23 Oct 2007

4 IBW_heating
[updated Feb 2006 (dmc)]
A rudimentary IBW facility has been added to TRANSP via TRDAT.
IBW heating profiles (computed elsewhere) may be supplied as
input to TRANSP.

Ufiles may be specified of IBW heating vs. (t,R).  Two Ufiles
are needed:

  IBI:  ion heating, watts/cm, vs. "midplane radius"
  IBE:  electron heating, watts/cm, vs. "midplane radius".

(These can also be specified as conventional power density profiles in
Watts/cm3, see below).

Optionally, two additional scalar f(t) Ufiles may be provided for
renormalization:

  PIB:  total ion heating, WATTS, vs. time
  PEB:  total electron heating, WATTS, vs. time

The IBI and IBE Ufiles are expected to be time dependent profiles, 
but, if only a timeslice profile is available this may be used and
constrained in time using the on/off time controls described below.

Namelist controls (TRANSP):

  MODIBW = 1  ! turn on the IBW data input option

By default, the on and off times are controlled by the time dependence
of the input data.  To override this, set:

  NLIBTFIX = .FALSE.      ! F to control on/off times from namelist

  TIBWON = <IBW on time>  ! (optional) on time; powers are zero
                          ! for t < TIBWON
  TIBWOFF = <IBW off time>  ! (optional) off time; powers are
                            ! zero for t > TIBWOFF

By default, NLIBTFIX=.TRUE. and the on/off times are set by the 
IBI and IBE data.  The on/off times from this data are then applied to
the PIB and PEB signals as well.

  ----------
  ** note **
  IBI and IBE powers can be input as W/cm3 instead of W/cm.  To
  indicate this, use:

  MODIBW = 2  ! input IBW heating profiles as W/cm3
  ----------

Summary of TRDAT namelist controls -- the usual profile input options 
are available; the following are the most likely to be modified:

  PREIBI,EXTIBI -- IBI ufile name prefix, suffix (heating profile)
  PREIBE,EXTIBE -- IBE ufile name prefix, suffix (heating profile)
  PREPIB,EXTPIB -- PIB ufile name prefix, suffix (total power to ions)
  PREPEB,EXTPEB -- PIB ufile name prefix, suffix (total power to e-)

  NRIIBI,NRIIBE -- Ufile range specifications
    Probably NRIxxx=1 or NRIxxx=3 will be used.  The data should
    actually cover the range claimed.  See info on TRDAT namelist
    for details.

  NXIBI,NXIBE -- internal resolution -- no. of spatial points
    mapped and copied for the TRANSP run.  This may have to
    be increased from the default value if the input profiles
    are sharply localized in space.  Use TRDAT interactive
    graphics options to determine if this is needed.

  on/off time control:  NLIBTFIX, TIBWON, TIBWOFF
  renormalizing scalar Ufiles:  PREPIB/EXTPIB and PREPEB/EXTPEB.

Output:

  TRANSP converts the data in watts/cm along the midplane to 
  watts/cm3 internally, line integrating within each plasma zone
  and then dividing by plasma zone volume.  The ion and electron
  heating terms are called PIBWI and PIBWE respectively.  These
  are fully incorporated into the power balance calculations
  and available in RPLOT after run completion.  A term labeled
  "IBW heating data input" appears in the scalar PHEAT multigraph.

4 PELLETS
Pellet injection events are specified through the namelist.

TRANSP namelist:
NPEL= number of pellet events
TPEL= list of NPEL pellet event times in ascending order of time
APEL= species (atomic weight) of injected pellet  (e.g. 2.0 for 
      deuterium); enter a number for each pellet

  APEL values must be drawn from the following sets:
    {1.0, 2.0, 3.0} -- isotopes of Hydrogen
    {6.0, 7.0} -- isotopes of Lithium

  Helium pellets are not allowed in the model (and probably cannot
  be manufactured in the real world, either).

MAXIMUM NUMBER OF PELLETS/RUN = 100

Note:  as of Jan 1995, the pellet ablation model no longer exists
in TRANSP.

NEW May 2002:  Multi-species pellets now supported.  To assign a
2nd specie to the j'th pellet in a run, set:

  FPEL2(j) = fraction of pellet which is the 2nd specie.
  APEL2(j) = Atomic weight of 2nd specie.  Values legal for APEL
             are legal for APEL2 as well.  APEL(j) and APEL2(j)
             should be distinct.

TRDAT namelist:
TPELDA = hazard time intervals, two numbers for each pellet event.
  The hazard time intervals specify the time region about each pellet
  event when the input UFILES data is not safe to use.  Within 
  these time ranges the data is extrapolated.  More details in the
  section on the TRDAT namelist.  TPELDA entries for "pseudo" pellets
  with NMPELA(j)=2 are ignored.
4 SAWTOOTH_MODEL
... new Aug 1986 ...

set NLSAW=.TRUE. to turn on the TRANSP sawtooth model

enter the precise sawtooth event times in UFILE form; specify the name 
via TRDAT namelist variables PRESAW and EXTSAW.  This UFILE is created
by doing a pattern recognition analysis on a timetrace of x-ray or ECE
data, using the program EXE:SAWTOO.EXE

All input UFILES may be expected to show DISCONTINUITIES at all
sawtooth event times.  For the sawtooth analysis to make sense these
measured discontinuities must be preserved in the smoothing process.
The sawtooth event times UFILE may be read in in the smoothing codes 
(GSMOO1/GSMOO2) to define define discontinuous breaks (interior endpts)
as an aid to preserving sawteeth while smoothing the temperature,
density, and other input data required by TRANSP.

  =====================================================
   IF YOU HAVE SMOOTHED THRU SAWTOOTH DISCONTINUITIES IN YOUR INPUT
   DATA, set 

     NLSAWD = .FALSE.    ! ... new switch DMC Aug 1988

   in the namelist.  The effect of this switch is to interpolate all 
   input data ignoring the sawtooth events, as in a normal run.  The
   sawtooth mixing will effect J, Ti, and fast ions, but will not
   effect Te, or any specie densities in this case, since quasi-
   neutrality relative to the input electron density data needs to
   be maintained.  This mode of operation is NOT RECOMMENDED.  If
   good sawtooth analysis is required, the input data should be 
   prepared accordingly.
  =====================================================

The output of the sawtooth model is a comparison of energy transfers
as predicted by the Kadomtsev model (cf e.g. KDSAW module in 
http://w3.pppl.gov/NTCC ) with measured energy transfers (in the case 
of electrons); or simulations in accordance with the Kadomtsev model,
in the case of ions and the plasma current profile.

As with pellets, a data "safety interval" must be set around each
event, specifying that the input UFILES data are not to be used
directly but extrapolated forward/back from nearby data to the
event time itself, in this time interval.  The half-duration of
this interval is specified by the namelist input DTSAWD

switches-- default .TRUE., set .FALSE. to turn off sawtooth model 
for...
  NLSAWE    electrons  (checked if Te is being predicted)
  NLSAWI    ions
  NLSAWB    beam fast ions
  NLSAWF    fusion product fast ions
  NLSAWIC   icrf minority fast ions

**1992 TRDAT SWITCHES**

The controls for handling data around events have been modified--
see the description under TRDAT_NAMELIST.

word to the wise-- run TRDAT interactively for new shot data, and
plot the results!

================================
NOTES ADDED AUGUST 1991 ...

The sawtooth model contains namelist control switches which up to
now have not been documented in TRANSPHELP.  These are XSWID1 and 
XSWID2 and XSWIDQ (added August 2006):

Switches which select between the Kadomtsev and Porcelli mixing models
are described elsewhere.

XSWID1 (default value: 0.0) controls the prediction of the response 
of ion temperature after the sawtooth.  For XSWID1=0.0, use the
Kadomtsev or Porcelli prediction to compute the change in the ion energy 
density profile.  Then divide out by the actual post sawtooth ion density
(determined by MEASURED DATA, not Kadomtsev/Porcelli theory) to yield the 
new ion temperature profile.  XSWID1=0.0 conserves total ion energy.
However, the new ion temperature profile can have an odd shape if
the measured density change is different from what the Kadomtsev/Porcelli
model would have predicted, or if the size of the sawtooth modeled
by TRANSP is different from what actually happened in the experiment.
As an alternative, set XSWID1=1.0 to use the Kadomtsev/Porcelli prediction 
for change of ion temperature and the data for change of ion density;
XSWID1=1.0 does NOT strictly conserve ion energy!  Values of XSWID1
between 0.0 and 1.0 give a sliding control between these two model
extrema.

XSWID2 (default value: 0.0) controls the prediction of the response
of the plasma current profile to the sawtooth event.  The default,
XSWID2=0.0, gives the full Kadomtsev/Porcelli predicted change in the 
current profile, i.e. (for full Kadomtsev) q=1 on axis and q>1 off axis, 
after the sawtooth. Setting XSWID2=1.0 causes there to be NO CURRENT 
MIXING, i.e. the current and q profile are modeled as unchanged by the 
sawtooth event. Setting XSWID2 between 0 and 1 gives a sliding control 
to select a model that "averages" between these two model extrema.

XSWIDQ (default value: 0.05) The Kadomtsev and Porcelli mixing models
produce current sheets which shows up as discontinuities in the Q profile.
This can cause the equilibrium solver to fail.  The XSWIDQ option sets
a finite thickness to the current sheet width in units of sqrt(normalized
toroidal flux) and is restricted to the range 0.0<XSWIDQ<0.10.

New 6 Sept 2007:

XSWFRAC_DUB_TE (default value: 0.0) controls what fraction of the change
in poloidal field energy density (due to the sawtooth) to apply to the 
thermal electrons.  This is of importance only if Te is being predicted;
Set XSWFRAC_DUB_TE=1.0 to recover behavior of code prior to 6 Sept 2007.
Notes:  (1) the change in (para/diamagnetic) toroidal field energy should
perhaps also be taken into account, but this is not available at the 
sawtooth time (because the MHD equilibrium is not immediately recalculated);
(2) if XSWFRAC_DUB_TE=1.0, and if the ad hoc current mixing somehow produces
a field that contains more energy than before the sawtooth, this will reduce
the electron temperature.  In one very low density case it actually caused
the temperature to go negative, crashing the code.

5 Porcelli_Sawtooth_Model

The mixing method described in Porcelli's paper 

  F. Porcelli, Plas. Phys. and Cont. Fusion 38 (1996) 2163.

had been implemented.  Also implemented are variants on the original
Kadomtsev model.

Default behavior is traditional Kadomtsev.  To select an alternative
behavior use the following namelist controls as described in 
freeshare/port.spec (NMIX_KDSAW=1, FPRCELLI=1.0 are the defaults).

  I  0  NMIX_KDSAW  = 1     ! Kadomtsev/Porcelli mixing option (KDSAW module)
        ! =1 -- standard Kadomtsev
        ! =2 -- Kadomtsev but with full particle mixing (instead of Helical
        !       flux matching method); predicted densities fully flattened.
        ! =3 -- Porcelli (see fporcelli) with two mixing regions, one for
        !       the "island" around q=1, and a second one for the axial
        !       region inside the island annulus.
        ! =4 -- Porcelli (see fporcelli) but with a single mixing region
        !       for predicted plasma species, covering both the q=1 island
        !       and the axial region.
        ! Kadomtsev mixing yields q>=1 everywhere; Porcelli mixing generally
        ! leaves a region with q<1 near the axis.  See KDSAW NTCC MODULE
        ! and kdsaw_pre_init subroutine call...

  D  0  FPORCELLI = 1.0D0   ! Porcelli fraction -- island width fraction
        ! =1.0 means q=1 island extends all the way to the magnetic axis XI=0
        !      and the mixing region is as big as it is for the Kadomtsev
        !      model;
        ! <1.0 means island reaches into (1-FPORCELLI)*XI(q=1).  There are
        !      two separate mixed regions, one being the magnetic island
        !      around q=1 of width controlled by FPORCELLI (extends to both
        !      sides of the pre-sawtooth q=1 surface), and the other being
        !      the axial region inside the annular region taken up by the
        !      q=1 island.  See KDSAW NTCC MODULE, kdsaw_pre_init subroutine.
 
5 Additional_Options_for_Fast_Ions

(DMC Nov. 2004) New options for "partial mixing" of fast ions (in the
NUBEAM Monte Carlo model) are now available.  There are three namelist
controls:

 XSWFRAC_ALLFAST -- fractional multiplier, all fast ions
 XSWFRAC_BEAM -- fractional multiplier, beam fast ions only
 XSWFRAC_FUSN -- fractional multiplier, fusion product fast ions only.

All these controls have default values of 1.0, and allowed values
between 0.0 and 1.0.

The NET FRACTION of beam injected ions participating in sawtooth 
mixing is:

   XSWFRAC_ALLFAST*XSWFRAC_BEAM

and the NET FRACTION of fusion product ions participating in sawtooth
mixing is:

   XSWFRAC_ALLFAST*XSWFRAC_FUSN

This allows the mixing fractions for these two classes of fast ions to
be specified together or separately.

4 MSE_POINT_SIMULATIONS
(New DMC 10 Dec 2004) 
(Provided at request of Asdex-U group according to their specifications)

=>Description: a namelist block is provided, for a generic, user defined
MSE simulation at a set of user defined (R,Z) points in the plasma
cross section.  Each point corresponds to one "detector".  The number
of detectors is given by the namelist control N_MSESIM (default: zero).
The R and Z locations are specified by namelist array sections:

  R_MSESIM(1:N_MSESIM) and Y_MSESIM(1:N_MSESIM)

(TRANSP uses Y instead of Z due to a coding convention reserving Z
to local variables).  Then, the coefficients

  AWGHT_MSESIM(1:10,1:N_MSESIM)

define the "response" of each detector to components of the equilibrium
B field and radial electrostatic field, according to the following 
formulae (gamma1 for the B field response only, gamma2 for B & E both):

gamma1(j)=(A1*B_R +A2*B_PHI +A3*B_Z)/(A6*B_R +A7*B_PHI +A8*B_Z)

gamma2(j)=(A1*B_R +A2*B_PHI +A3*B_Z +A4*E_R/v_b +A5*E_Z/v_b)/
          (A6*B_R +A7*B_PHI +A8*B_Z +A9*E_R/v_b+A10*E_Z/v_b)

for detector j, j varying over 1:N_MSESIM; A1=AWGHT_MSESIM(1,j),
A2=AWGHT_MSESIM(2,j), etc...

The quantity v_b in the gamma2 expression is the "neutral beam
velocity" this can either be input directly through the namelist, or,
taken from the neutral beam data, as follows, for detector j:

  set NB_MSESIM(j) = +[neutral beam index number]
  ...for v_b to be taken from the full energy component velocity
  of the indicated beam as defined in the TRANSP namelist, or,

  set NB_MSESIM(j) = -[eV/AMU of beam corresponding to v_b]
  ...e.g. for a 60KeV Deuterium beam set NB_MSESIM(j)=-30000

  NB_MSESIM(1:N_MSESIM) have to be defined.

Outputs (available in RPLOT and the TRANSP NetCDF/MDSplus output):

All are profiles, plotted against detector index # (1:N_MSESIM):

  VBA_MSE (profile)  -- beam energies/AMU corresponding to v_b
                       used for each detector simulation

  X_MSE (profile) -- normalized flux coordinate location of
                     (R_MSESIM,Y_MSESIM) real space points;
                     set to 1.1 for points beyond the boundary.

  B_MSE (multigraph) -- B field components at each dectector (R,Z), Tesla

  E_MSE (multigraph) -- E field components at each dectector (R,Z), V/M

  GAMMA_MSE (multigraph) -- gamma1 and gamma2 signals as defined above.

--------------------------------------
Note: care should be taken that the orientations of the toroidal
field and toroidal current are correctly specified in the TRANSP
simulation (i.e. use NLBCCW and NLJCCW or make sure the data is
given to TRANSP via the MHD equilibrium or equilibrium boundary
input data).

--------------------------------------
Caution to Asdex-U users!  An extra coefficient (A5 for E_Z in the
numerator) has been added, so the coefficient definitions are
accordingly shifted relative to your original specifaction!
  
4 CHORDAL_SIMULATIONS
some simple diagnostic simulators have been added to TRANSP:

chordal density measurement (interferometer array):

set:  NLDA = no. of chords; for each chord j, set:
        RLDA(J) = start radius of chord, cm
        YLDA(J) = start elevation of chord, cm
        THLDA(J) = poloidal aiming angle of chord, degrees
        PHLDA(J) = toroidal aiming angle of chord, degrees

NOTE:  Faraday Rotation integrals are also calculated on the
above chords.

chordal visible bremsstrahlung detector array:

set:  NVBA = no. of chords; for each chord j, set:
        RVBA(J) = start radius of chord, cm
        YVBA(J) = start elevation of chord, cm
        THVBA(J) = poloidal aiming angle of chord, degrees
        PHVBA(J) = toroidal aiming angle of chord, degrees

X-ray crystal (doppler Timpurity) detector array:

set:  NXCA = no. of chords; for each chord j, set:
        RXCA(J) = start radius of chord, cm
        YXCA(J) = start elevation of chord, cm
        THXCA(J) = poloidal aiming angle of chord, degrees
        PHXCA(J) = toroidal aiming angle of chord, degrees
        EEXCA(J) = Excitation energy, eV, of impurity line to
                   use for signal integral, chord J

collimated neutron detector array

set:  NNTA = no. of chords; for each chord j, set:
        RNTA(J) = start radius of chord, cm
        YNTA(J) = start elevation of chord, cm
        THNTA(J) = poloidal aiming angle of chord, degrees
        PHNTA(J) = toroidal aiming angle of chord, degrees


"General Chord Simulation" array

set:  NGCH = no. of chords; for each chord j, set:
        RGCH(J) = start radius of chord, cm
        YGCH(J) = start elevation of chord, cm
        THGCH(J) = poloidal aiming angle of chord, degrees
        PHGCH(J) = toroidal aiming angle of chord, degrees

Presently the "General Chord Simulation" outputs electron
temperature and density profiles mapped along the specified
chords.  For each chord a set of outputs to RPLOT is created.
For example, for chord 3 the following RPLOT functions are
computed:

  RXGCH3 -- R location of chord pts in plasma
  YXGCH3 -- Y location of chord pts in plasma
  XXGCH3 -- "r/a" of flux surface on chord pts in plasma
  LXGCH3 -- length (cm) from chord start pt to pts in plasma
  NEGCH3 -- electron density at chord pts in plasma
  TEGCH3 -- electron temperature at chord pts in plasma

These functions may be plotted against eachother, e.g.
NEGCH3 vs LXGCH3 (for more information see the manual
"Accessing TRANSP Output, A User's Guide" which gives
instructions on using RPLOT).

In addition, detailed chord profile data on fusion rates is now 
output.

The namelist control NGCHPTS controls the number of profile points 
saved along each chord; the number of points needed to contain all 
plasma zone chord intersections depends on the chord aiming; 
tangential views need more points.  A minimum of 3*NZONES is 
recommended and may be enforced in a future version of the code.

=========================================

If both the poloidal and toroidal angles given are zero, then,
the chord is taken to be a horizontal chord looking directly 
in towards the machine centerline, from a large major radius 
position.

POSITIVE poloidal angle denotes a chord pointing up towards higher
elevation; POSITIVE toroidal angle denotes a chord pointing into 
the plasma current (however this sign convention is immaterial for
these simple axisymmetric simulations).

See also the section "EFLUX_SIMULATION" for information on 
charge-exchange and bolometer simulations.

4 EFLUX_SIMULATION
WARNING:  TRANSP employs simple 1d flux surface averaged neutral
density profiles.  3d effects on plasma charge-exchange eflux CANNOT
be modeled with the existing code.

...a rewrite of these namelist controls is proposed...

set NLEFLX=.TRUE. to turn on neutral eflux modeling system.  Then:

5 CX_spectra
output of this system is neutral eflux plots vs. time and energy
for selected chords.

update Feb2003: The eflux code has been rewritten to include
neutral beam contribution to the eflux, use of more detailed zone
and monte carlo zone info for computing the eflux and additional
diagnostic controls.  The namelist controls have been changed so
old namelists will not work without modification,

NCXANG = number of distinct charge exchange spectra chords to trace

if i = chord index,
CXRSTA(I)= radius (dist. from machine centerline) of CX pivot
CXYSTA(I)= elevation (dist. above/below midplane) of pivot
CXZETA(I)= toroidal position of pivot in degrees (ccw is positive)
           (see XBZETA(IB) for setting the corresponding beam
            toroidal angle.)

CXRTAN(I)= tangency radius of CX sightline, positive to view 
           corotating particles, minus for viewing counterrotating
CXTHEA(I)= angle of chord with respect to midplane,+ is up,- is down

if j = the detected species index for chord I
NIGCX_Z(J,I)    = atomic number of CX species detected on chord I
XIGCX_A(J,I)    = atomic weight of CX species detected on chord I
NIGCX_ENGY(J,I) = energy table index to be used for eflux

All species AMU will be normalized to proton mass, for details see (5) Plasma.


if k = energy table index
NCXENY(K) = number of energies in the table
CXENMN(K) = minimum energy in table (eV)
CXENMX(K) = maximum energy in table (eV)
NLCXLOG(K) = .true.->table is logarithmic, .false.->for linear

for m = neutral source index
CXWTN0(M,I)= neutral weighting factor (btw 0 and 1) for chord i,
         neutral source M=1,2, or 3.  1= "warm" wall source, 2=
         "volume"/"beam halo" source; 3= "cold" wall source.
         default is CXWTN0=1.0.

CXWBN0(M,I)= neutral weighting factor (btw 0 and 1) for chord i,
         fast neutral source M=1,2,3 or 4.  1= beam neutrals
         at full energy,  2= beam neutrals at half energy,
         3= beam neutrals at one third energy, 4= nth generation
         fast neutrals (fast ions which have been neutralized by
         charge exchange with the beam or thermal or fast neutrals). 
         default is CXWBN0=1.0.

NLEFLX_FLR = set .TRUE. to use the fast ion distribution evaulated
         at the gyro, .FALSE. to use the fast ion distribution evaluated
         at the guiding center.  If the FLR fast ion distribution was based
         on all three degrees of freedom of the velocity, this switch
         wouldn't make a difference but the FLR distribution loses information
         about the gyro phase.  So with the FLR distribution, the CX flux
         can include contributions from fast ions which don't actually
         follow the path of the neutral particle analyzer.  The default
         is .FALSE. to use the guiding center distribution.

The neutral density in the beams is computed using tubes as described
in Beam_Neutral_Density.  Most of the tube parameters are computed
automatically from the CX chord info except for the tube namelist 
controls which are shared by all tubes.  Infomration on how well the
defaults were chosen can be found in the <runid>TR.INF file. The 
most relevant namelist variables which may need to be set are,

  RHOTUBE = radius of the tube (cm), the smaller the tube the more 
            trajectories which are required to get a decent density
            statistic
  LMIDTUBE= defaults to 1.  Should be kept as 1 when used as eflux.
  XL1TUBE,XL2TUBE = define the data collection limits.  This is 
            computed automatically based on the CX chord/beam 
            intersections but can also be set by hand.
  NSEGTUBE= number of data collection segments
  NDEPTUBE= scale the number of monte carlo trajectories used to
            compute the beam neutral density. (defualt 500)

A small number of diagnostic CX eflux tests can be made at a fixed
energy during each time step.  The data is returned over a CX
sightline grid in cm measured from the CX pivot points.

NCXSIGHT = number of points in CX sightline (default 6*nzones)
XCXSIGHT = length of CX sightline (default twice the distance
           to the tangency point).  The default is probably too
           long so it would be wise to override this.
XCXSIGHT0= distance from pivot of when to begin the CX sightline 

if n = diagnostic index
NCXDIAG_CHORD(N) = index of CX chord for this diagnostic
NCXDIAG_Z(N)     = atomic number of diagnostic species
XCXDIAG_A(N)     = atomic weight of diagnostic species
XCXDIAG_ENGY(N)  = energy of diagnostic species (eV)
The diagnostic species must match a regular CX eflux species
on the same chord.

outputs from the CX eflux include,
 CXFE<i><sp> = CX eflux in units of 1/(cm**2*sec*eV^1.5) evaluated
               over the energy table axis where
                <i>  = CX chord index
                <sp> = species label (e.g. H, D, T, Be9, ...)

tube transp outputs,
 TUBE0_<i> = beam neutral density for tube number <i>

diagnostic outputs for diagnostic index <n> along the CX sightline
grid,
 DCXFL<n>  = CX eflux at the diagnostic energy -- this is a
             scalar function and does not include the 1/sqrt(ev)
             normalization used in CXFE<i><sp> (1/(cm**2*sec*eV))
 DCXDT<n>  = ion distribution function towards the detector from 
             thermal species (1/cm**3/eV)
 DCXDF<n>  = ion distribution function towards the detector from 
             fast ions (1/cm**3/eV)
 DCXRT<n>  = CX production rate from thermal neutrals (1/sec)
 DCXRF<n>  = CX produciton rate from fast neutrals (1/sec)
 DCXATT<n> = attenuation factor due to CX of eflux neutral with 
             background thermal and fast ions (-)
 DCXDFL<n> = differential CX eflux at the diagnostic energy
             1/(cm**3*sec*eV)
 DCXPA<n>  = Vparallel/V with the sign relative to the plasma current
             direction.  This relates to the pitch angle sampled from
             the distribution function along the eflux chord. (-)
 DCXBN0<n> = total neutral beam density (1/cm^3)
 DCXFN0<n> = total nth generation fast neutral density (1/cm^3)
 DCXHN0<n> = total thermal neutral density due to warm wall 
             sources (1/cm^3)
 DCXVN0<n> = total thermal neutral density due to volume (halo)
             sources (1/cm^3)
 DCXCN0<n> = total thermal neutral density due to cold wall
             sources (1/cm^3) 
 DCXEPL<n> = energy of the neutral particle in the plasma frame (eV)
 DCXEBM<n> = average energy of the neutral particle in the beam 
             frame (eV)
 DCXEFA<n> = average energy of the neutral particle in the nth 
             generation fast neutral frame (eV)
 DCXETH<n> = average energy of the neutral particle in the 
             thermal neutral frame (eV)
 DCXXI<n>  = sqrt(normalized toroidal flux) along sightline
 DCXRMJ<n> = major radius along the sightline
Except for DCXXI and DCXRMJ, the name of the multigraphs of these 
rplot signals over the diagnostic indices is formed by replacing
<n> with 'm' in the above rplot signal names.

note -- if using the Monte Carlo code to simulate eflux spectra from
  a slowing down beam population, with eflux generated from wall
  source neutrals, consider using the WGHTA control in the beam 
  Monte Carlo code -- see description under beam code heading:
  general controls.

6 TI fit to eflux data
Assuming a maxwellian distribution which does not change significantly
over the dominant eflux section of the sightline,
  flux =approx= Fmaxwell_E * sum(Nneut*<sigma*v>) * Atten * L
where
  Nneut = neutral particle density, the summation is over species
  Atten = attenuation
  L     = length of sightline
  Fmaxwell_E = (2*N/T)*sqrt(E/(pi*T))*exp(-Eplasma/T)
The eflux spectrum is a scaled version of the flux given by
  spectrum = flux * sqrt(pi/E)/(2*<sigma*v>)
           =approx= N/T**1.5 * sum(Nneut*<sigma*v>)/<sigma*v> 
                    * Atten * L * exp(-Eplasma/T)
Assuming the plasma rotation is small enough so that the energy of
the neutral in the plasma frame is about the same as the lab frame,
the log(spectrum) has a linear relationship to the eflux energy with
a slope inversely proportional to the ion temperature.  An estimate of
the ion temperature can be calculated from the eflux with the following 
namelist switches indexed similarly to NIGCX_Z(J,I),

if j = the detected species index for chord I
  CXLMLO(J,I) = lower bound of eflux energy included in TI fit
  CXLMHI(J,I) = upper bound of eflux energy included in TI fit
  CXMULO(J,I) = an eflux energy E is rejected for inclusion in the fit
                if E<CXMULO(J,I)*estimated_TI
  CXMUHI(J,I) = an eflux energy E is rejected for inclusion in the fit
                if E>CXMUHI(J,I)*estimated_TI
  CXFLMN(J,I) = minimum flux allowed to be used in TI fit

if CXMULO(J,I)==CXMUHI(J,I)==0., the TI fit will be skipped

As an alternative, a TI fit range can be read in from a Ufile and used
for the TI fit on one species on one sightline.  This requires,
  NLPCX  = .TRUE. -> compare TI fit to ion TI
  NLPFIN = .TRUE. -> use Ufile data to bound TI fit energy range
  NCHPCX = chord index for this custom fit range
  NSPPCX = species index
The PFL and PFH Ufiles will be read to supply the lower and upper
energy ranges for the TI fit for species NIGCX_Z(NSPPCX,NCHPCX).

rplot outputs for the TI fit are (naming similar to CXFE),
  CXSP<i><sp> = eflux spectrum (1/(cm^5*eV^1.5))
  CXTI<i><sp> = estimated ion temperature (eV)
  CXIN<i><sp> = E=0 intercept of spectrum (1/cm^5)

5 Bolometer_eflux
Feb2003, this has been temporarily disabled

4 Limiter_locations
New DMC Nov. 2006:  instead of using the circle & line limiters, 
A contour limiter can be defined from Ufile input {PRELIM,EXTLIM}.
This Ufile contains {R_i,Y_i} as a closed contour in the form Y(R).

(In parts of the documentation the notation (R,Z) is used instead
of (R,Y)).

The TRANSP data preparation software "scrunch2" can extract such
data from EFIT file or MDSplus data.

If the PRELIM,EXTLIM Ufile data is detected, it overrides any of
the namelist information described below.

----------------------
Traditional TRANSP limiter representation:

Physical limiter locations are input to TRANSP via the namelist.
These limiters are assumed to extend toroidally all the way around
the vacuum vessel (for computational simplicity).  Two types of
limiters may be specified:
  circular
  infinite straight lines.
At the start of a run, a test point is located inside the plasma.
For the remainder of the run, the space on the other side of all 
limiters from the test point is inaccessible to beam ions and 
straight sight lines (TRKRB).  SET

NCIRLM = number of circular limiters
CRLMR1(J) = MAJOR RADIUS of center of circle (cm)
CRLMY1(J) = elevation of center circle above/below midplane (cm)
CRLMRD(J) = radius of circle describing limiter

NLINLM = number of infinite line limiters
ALNLMR(J) = R coordinate of any point on the line
ALNLMY(J) = Y coordinate of any point on the line
ALNLMT(J) = orientation of line in DEGREES.  45 degrees points UP and
            INWARDS in R.  -45 degrees points DOWN and inwards in R.

CAUTION - if at any time the specified plasma boundary and a limiter
intersect, the code will stop with an error message.  (A few mm of slop
will be tolerated).
4 TIME_CONTROL
ALL TIMES ARE IN SECONDS!

TRANSP namelist controls:
  TINIT - START TIME of TRANSP analysis.
  FTIME - STOP TIME of TRANSP analysis.
ALL UFILES DATA analyzed by TRANSP is taken from this timerange ONLY.
Proper selection of TINIT and FTIME depends on the nature of the 
UFILES data and the analysis being attempted.

  FTIME_OK -- if a TRANSP run makes it this far (even if short of
FTIME) consider it a "success".  FTIME_OK defaults to a very large
number, but, by setting it to a value less than FTIME one can cause
the code to ignore crashes and exit normally if the crash occurs 
between times FTIME_OK and FTIME.  This provides a way e.g. to
specify that a run should get "as close as possible" to the end of
a discharge, without inducing a crash that requires hand post-
processing.

Sample considerations:
  a)  electron temperature and density data available for the timerange
selected.
  b)  if ion conduction feedback to neutron data is on, be sure that 
there is a useable neutron signal in the timerange selected.
  c)  if resistivity Zeff adjustment to surface voltage data is used, 
it may be desirable to constrain the run to times when the voltage 
is positive, as the adjustment loop tends to go unstable, for 
physical reasons, when the voltage goes negative i.e. in
the terminal phase of the discharge (because the voltage becomes
relatively insensitive to Zeff changes with the total plasma current
boundary condition fixed).

5 Data_interpolation
The preprocessor TRDAT interpolates UFILES data to two fixed time 
grids covering the time range TINIT to FTIME.

namelist quantities
  TGRID1 -- spacing btw. time pts for SCALAR input data.
  TGRID2 -- spacing btw. time pts for PROFILE input data.

THESE QUANTITIES ARE THE PRIMARY CONTROLS OF THE TIME RESOLUTION
OF THE DATA AS TRANSP SEES IT.

TRANSP will re-interpolate from this TRDAT grid to arbitrary time
between TINIT and FTIME as needed.

The two TRDAT grids are evenly spaced in time except:
  (a) when sawtooth or PELLET events occur (see information on 
      sawteeth and pellets), or
  (b) when a ZOOM (high time resolution time interval) is in
      effect -- see description of ZOOM feature and controls.
5 timesteps
TRANSP calculations are controlled by a hierarchy of timesteps.
There are two broad classes of timesteps:

  Fixed:  data input controls the timestep, subject to constraints.

(Heating and current drive sources are updated using a time step which
is fixed except when adjustment is necessary to meet flush with time
events).

  Self-adjusting:  code has a timestep adjustment algorithm 
which will attempt to scale a timestep usually to avoid too large
a discreet (single step) change in some signal quantity.  Data
input specifies the MAXIMUM allowable step and the MINIMUM allowable
step.  A request for a step smaller than the MINIMUM step causes 
TRANSP to halt with error messages (CRASH).  Self-adjusting steps
also usually include a namelist input to specify the INITIAL step
length.

(Transport equations and equilibrium are updating using a self-adjusting
time step).

In addition, timestep boundaries are constrained by "time events", such 
as:

START of run                 END of run
PELLET injection             commencement of NEUTRAL BEAM injection
Prescribed Sawtooth          ZOOM-IN/ZOOM-OUT timestep control
Restart of NEUTRAL BEAM injection (e.g. start of each "beam blip").

==> June 2005 (dmc) -- timesteps for all heating
sources (ECH/ECCD, LH, ICRF, neutral beams) are merged:

   DT_SOURCES = DTLH = DTICRF = DTECRF = DTBEAM = DTMAXG

The choice amongst the separate heating models' legacy namelist
time step controls is made in source/trutil/set_dt_sources.f90 --
basically, if NLBEAM is set, DTBEAM is used, then if NLICRF is
set, max(DTMAXG,DTICRF) is used, ...etc...

The maximum timestep for geometry, DTMAXG, is (except for ICRF)
independent of DT_SOURCES and can be set to a smaller value if
necessary.

FIXED timestep controls in TRANSP namelist:
  DT_SOURCES -- fixed timestep for heating and current drive sources
   of all types...

self-adjusting timestep controls in TRANSP namelist:
  DTMING, DTMAXG, (DTMAXG/2):  time step for advance of MHD
    equilibrium.
  DTMINT, DTMAXT, DTINIT:  min, max and initial timestep for
    evaluation of ion and/or electron particle and energy balance
    calculations.  Stepsize controlled by changes in temperature
    or density.
  DTMINB, DTMAXB, DTINIB:  ditto for poloidal field diffusion.
    Stepsize controlled by changes in the poloidal field or total
    plasma current.
  DTCONM:  maximum poloidal field equation "lead" step.  When the
    electron temperature is input to TRANSP, the poloidal field
    equation may be solved (with an independent series of timesteps)
    in advance of the ptcl/energy balance equation, with this
    amount of lead time.  Minimum lead step is MAX(DTMINB,DTMINT)
    since poloidal field AND ptcl/energy steps are contained within 
    this step.  Stepsize is controlled by change in resistivity Zeff.
    However, as Zeff may change relatively slowly, the steplength will
    often assume the value DTCONM.  The INITIAL stepsize is DTINIT.

  DTMAXG:  maximum timestep for MHD plasma equilibrium geometry
    evaluation if LEVGEO.GT.0 (see Geometry_Level subkey).  This
    step constrains all others, thereform minimum timestep is
    MAX(DTMINT,DTMINB).  Step is controlled by macroscopic 
    properties of the equilibrium or input boundary (see 
    GFRAME.FOR).  The INITIAL steplength is DTMAXG.  It usually
    stays there unless there is a fast change in the plasma
    boundary (i.e. compression experiment).  (dmc: see June 2005
    note, above.  If the geometry timestep is shortened, then the
    timesteps for all sources will be shortened as well).

See also:  TGRID1/TGRID2 -- control time resolution of input data
           SEDIT/STEDIT -- control time resolution of output data

6 Time_dependent_time_step_controls
Historically, time steps are controlled through the namelist.  In 
addition, there is a "zooming" feature (TZOOM array) that allows 
timesteps to be temporarily reduced at prescribed times in the 
course of a run.

If TZOOM is NOT used, there is another option.  The following time
steps themselves can be prescribed as functions of time via 1d
f(t) Ufile or MDSplus signal input to TRDAT:

  DTMAXG (max equilibrium time step):  TRDAT input (preDTG,extDTG)
  DT_SOURCES (time step for heating):  TRDAT input (preDTS,extDTS)
  SEDIT/STEDIG (output time resolution):  TRDAT input (preDTX,extDTX).
    (SEDIT is controlled by DTX; the ratio STEDIT/SEDIT as given in
    the namelist is preserved).

The RPLOT output multi-graph DTS contains the actual time steps used
as a function of time:
  DT -- time step for transport equations
  DTG -- time step for equilibrium advance
  DTSCE -- time step for sources
  DTSCALAR -- time resolution of scalar f(t) outputs
  DTPROFIL -- time resolution of profile f(x,t) outputs

5 Output_control
The TRANSP namelist output controls determine how frequently output 
data records will be written.  Specifically:

SEDIT determines the time spacing between profile data output records.
STEDIT determines the time spacing between scalar data output records.

Thus if SEDIT=0.01, TINIT=0.2, and FTIME=0.3 there will be 11 profile
output records at t=0.2,0.21,...,0.30.  

The SEDIT and STEDIT controls are not exact since TRANSP can only 
output when timesteps are complete.  However, the output timing 
algorithm stays as close as possible to these controls, and errors
due to finite timesteps are not allowed to "accumulate".  The setting
of a positive SEEDIT (see ELVIS_output) will force SEDIT==STEDIT (the
minimum of the two values will be taken).  This is the default and 
is generally recommended.

Events (such as sawteeth) can cause extra output records to be 
generated.

5 Equilibration_option
[DMC Oct 2007]

In TRANSP, calculation of heating and current drive sources often
dominates the running time of a simulation.  For simulations in which
there is a long "flat-top" with little change in plasma parameters
or MHD equilibrium, it may be desirable to stop recalculating the
sources, and hold them fixed until the plasma changes or there is 
some event such as a sawtooth or pellet.  This will greatly speed the 
time advance of the model during the flat-top phase.

So, an equilibration option has been added to the TRANSP heating and
current drive source calculation control.

To activate this, set the namelist variable

  noption_equil = <(# of comparison zones), a number greater than 0>

By default the model is off; i.e. noption_equil=0.  The number of 
comparison zones is the number of plasma regions over which to integrate
quantities for comparisons.  The minimum number is 2; the maximum is 10.
If noption_equil=1 it is reset to 2; if noption_equil>10 it is reset to 10.

The plasma will be declared equilibrated if change in total plasma specie 
populations and energy content in every comparison zone is less than
a threshold value, since the last de-equilibration event (i.e. since the
last sawtooth, pellet, or over-the-threshold change in plasma parameters).

Also checked for equilibration are: rotation energy,
poloidal field energy, fast ion transport, and, total plasma current
and plasma boundary location.  If a sawtooth or pellet occurs, or if
there is a model event (e.g. change in transport model at a prescribed
time in the namelist), equilibration is terminated.

Here are the namelist controls (default values in parentheses):

  flattop_var    (0.02)   -> max allowed relative change in Ip, 
                             R*B_phi(vac), and Rmajor of outer flux surface

  change_event   (0.06)   -> max allowed change in specie population or
                             energy content, rotation energy, poloidal 
                             field energy, or fast ion transport

  equil_time     (3.00)   -> number of "slowing down times" needed to
                             reach equilibrium

  equil_avg_time (1.00)   -> number of "slowing down times" over which
                             to average heating and current drive sources

And...

  t_force_equil  (1.0d34) -> time at which to UNCONDITIONALLY FORCE the
                             code into source equilibration

If t_force_equil (seconds) is between TINIT and FTIME, the heating and
current drive sources are fixed and have no time variation from time
t_force_equil onward until the end of the run.

5 Event_times
namelist arrays and scalars:

TPEL determines pellet injection times.  See description of namelist
     quantities to describe PELLETS.  See also the TRDAT namelist re.
     data timing information array TPELDA.  (array)

TBONA determines beam turn-on times.  The earliest value of TBONA must
     be .GT. TINIT.  (array)
TBOFFA determines beam turn-off times.  (array)
     see section on NEUTRAL_BEAMS.

5 ZOOM_feature
It is often desirable to have a higher time resolution calculation and
output around certain "interesting events" in a discharge simulation,
e.g. pellet injection or compression.  An easy way to do this
in TRANSP is provided by way of the TZOOM array.  Set

TZOOM = t1,t2,t3,t4, ...

The ZOOM is "on" in time intervals (t1,t2), (t3,t4), etc.
It is "off" at all other times.  The specified times must be in
ascending order and in pairs, terminated by a zero element.  The
time intervals must not overlap, and they must not cover the initial
time TINIT.

When the ZOOM is on, the following timesteps (or timestep maxima) are
reduced by a factor of ten:

DTMAXT, DTMAXB, DTCONM, DTBEAM, SEDIT, STEDIT  (see section on 
timesteps for definitions).

In addition, the output time spacing parameters SEDIT and STEDIT
are reduced by a factor of 10 for ten times more frequent output.

The number of Monte Carlo particles during zoom periods is controlled
by int(PZOOM(8)) (see note on PZOOM, below).  If this is defaulted,
the number of Monte Carlo particles is quadrupled during zoom periods.

When ZOOM turns off the original control settings are restored.

These characteristics of ZOOM may be modified via the namelist 
array PZOOM.  For details check out the subroutine which implements
the ZOOM feature:  source/trulib/szoom.for.

Here is a description of PZOOM controls as of Aug. 2009:

PZOOM info -- from trulib/szoom.for -- default values are ZERO, 
which cause default timestep changes to be used.  Default changes
are shown in parentheses.  Example of interpretation: "1/20 the original
value" for PZOOM(1)=0.0 means that on zoom in, DTMAXT is reduced to
(1/20th) its original value; on zoom out, the original value is restored.

  PZOOM(1) = <new maximum transport time step (1/20 the original value)>
    (non-zoom default: 2.0e-3 seconds: DTMAXT).
  PZOOM(2) = <new maximum poloidal field time step (1/20 the orig. value)>
    (non-zoom default: 1.0e-3 seconds: DTMAXB).
  PZOOM(3) = <new resistivity Zeff time step (1/10 the orig. value)>
    (non-zoom default: 5.0e-3 seconds: DTCONM).

  PZOOM(4) = <time time step for NUBEAM & other heating (1/10 the orig. value)>
    (non-zoom default: 5.0e-3 seconds: DTBEAM).
    This is the frequency of calls to NUBEAM, FPPMOD/ICRF, ECH, LHCD
    models-- same time control is now used for all auxilliary heating
    and current drive models.

  PZOOM(5) = <maximum geometry timestep (1/10 the orig. value)>
    (non-zoom default: 10.0e-3 seconds: DTMAXG).

  PZOOM(6) = <profile output time step (1/10 the orig. value)>
    (non-zoom default: 10.0e-3 seconds: SEDIT).
  PZOOM(7) = <scalar output time step (1/20 the orig. value)>
    (non-zoom default:  5.0e-3 seconds: STEDIT).

  PZOOM(8) = <NPTCLS for Monte Carlo beam ions (increase by factor of 4)>
    (non-zoom default: 1000 particles: NPTCLS).
    (Fusion Monte Carlo particle count NPTCLF is scaled up by the same 
     factor as NPTCLS).

  NOTE: PZOOM(9:50) are not in use.

*IMPORTANT*
TRDAT IMPLEMENTATION:  The spacing of interpolation times for input
UFILES data is ten times denser (than specified by the TGRID1 and 
TGRID2 parameters) during the ZOOM intervals.  Thus the ability to 
follow rapid changes in the input data is greatly increased via ZOOM.

5 Initial_wait
The namelist parameter TWAIT specifies the amount of "physical
pseudo-equilibration time" (seconds) to spend intializing the 
plasma parameter profiles in the INITAL subroutine before commencing
the TRANSP time forward solution of the model equations.  The 
default value of TWAIT=0.1 seconds is adequate for most purposes.

See Code_Structure section for information on INITAL.

5 Abort_times
New June 1987...

Set the namelist array TABORT(j), j=1,2,...,(up to) 8, to specify
times where TRANSP should write a restart file and abort, for
debugging purposes.

Set the first time in TABORT(1); the second time in TABORT(2), etc.
The times must be specified in ascending order; all times must fall
between TINIT and FTIME (inclusive).  The first TABORT value not in
this range ends the list; subsequent array elements are not scanned.
4 Ballooning_package
From:	SMTP%"bateman@theory.pppl.gov" 19-MAY-1993 23:12:15.86
To:	TRANSP@pppl.gov
Subj:	Ballooning Modes in TRANSP, BATEMAN

        The ballooning mode package in TRANSP computes the pressure
gradient needed for the first stability of high-n ideal MHD ballooning
modes.  

This package integrates the ballooning mode differential equation around
each flux surface using a numerical routine provided by Mike Phillips at
Grumman.

There is also an evaluation of the analytic stability criterion by 
Pogutse, Chudin, and Yurchenko [Sov. J. Plasma Phys., 6 (1980) 
341--345, Eq. (24)].  The package was implemented in TRANSP by 
Glenn Bateman, PPPL.  The routines are well documented using LaTeX.

        In order to use the ballooning mode package in TRANSP, set
CBALLOON(1)  = 2.0  ! This turns on both numeric and analytic models
CBALLOON(20) = 2.0  ! This smooths p'(r) profiles by applying
                    ! u(j) = 0.25 * ( u(j+1) + 2.*u(j) + u(j-1) ) twice
CBALLOON(21) = 1.0  ! This smooths q'(r) (smoothing applied once)

        To examine the output using RPLOT, first look at 
BLNFRAC  which is a scalar equal to the fraction of the radius that is
unstable, as a function of time

BLNDPDR  which is a multiplot as a function of r and time consisting of
        BDPDRCR  is the numerically computed critical pressure gradient
                 for high n ideal ballooning modes on each flux surface
        BDPDRAN  is the analytic critical pressure gradient using the
                 analytic expressions of Pogutse, Chudin, and Yurchenko
        BDPDRTR  is the equilibrium pressure gradient used in TRANSP
These profiles of p'(r) are generally negative.  The mode is unstable
in regions where BDPDRTR is more negative than BDPDRCR.

        Every effort has been made to make the package bullet-proof 
so that it will not fail even when it encounters unusual situations.
For example, when q'(r) or p'(r) is negative, the package sets 
BDPDRCR = 0.0 and does not include this point in BLNFRAC.  The values 
of BDPDRCR or BDPDRAN are not set to large values under these 
conditions because the scale of the plots in RPLOT needs to be kept 
consistent with the rest of the values of BDPDR...  There are numerous
other safeguards in the package, so it should never fail.  If there 
is ever a problem, please send a mail message to bateman@pppl.gov.

Glenn Bateman (PPPL)
bateman@lyman.pppl.gov 
Phone: (609) 243 2837
FAX:   (609) 243 2160

4 Boundary_Conditions
References are to sibling topics (under NAMELIST...).

Plasma boundary location:  determined by equilibrium flux surface
  model options chosen -- see PLASMA_BOUNDARY and MHD_GEOMETRY.
  In the future a free boundary version of TRANSP -- last closed
  surface computed on the fly -- will be provided.

Magnetics boundary conditions -- see MAGNETICS.  Generally, data
  is provided for total plasma current, vacuum toroidal field R*Bt,
  and surface voltage.

Gasflow and Recycling Neutral sources -- the edge neutral source
  energies may be controlled.  See PTCL_BAL Neutrals.

Temperature predictive models:
==============================

Ion Temperature -- several options are provided:
  MODIEDG=1 & MOD0ED=1 (default) use namelist input TIEDGE.
  MODIEDG=1 & MOD0ED>1 -- use MOD0ED option described under
    PTCL_BAL Neutrals
  MODIEDG=2 -- use TIEDGE (ignore MOD0ED).
  MODIEDG=3 -- use Te input data (Ufile data) at the edge.
  MODIEDG=4 -- use Ti input data (Ufile data) at the edge.

Electron Temperature -- 
  MODEEDG=2 -- use namelist input TEEDGE.
  MODEEDG=3 (default) -- use Te input data at the edge.

The temperature boundary conditions are output to RPLOT as
scalar functions of time, RPLOT names are TEEDG and TIEDG.

3 TRANSPruns
 **(dmcApr16:  this and subtopics to be rewritten)**
 **(dmcApr16:  end of section marked by dmcApr16 below...)**

This section describes how to start, stop, and restart TRANSP runs
on the PPPL UNIX Cluster.

It is assumed that the user has a namelist and a complete set of
Ufiles, i.e. the TRANSP run is ready to go.

In this case, the simplest procedure is (1) run pretr, and (2)
use enqueue to start the run.  In many cases this is all you
need to do.

**Important Change**>  TRANSP now assumes a multiuser environment.
Most users will create their namelists in their own account in a
directory created for that purpose.  From this directory the user
can run xtranspin, trdat, tr_start and tr_send, tr_cleanup, to queue
or interrupt his or her TRANSP runs. 
USERS DO NOT HAVE TO LOGIN TO the TRANSP account in order to operate TRANSP.

** caution ** this section is oriented to PPPL Production runs.
Users who want to setup their own TRANSP production system should see
the document "codesys/source/doc/qmanager.doc" in the TRANSP
source code distribution, and see 
	http://w3.pppl.gov/transp/ComputeServerAccess.html
        Managment and Implemetation

4 SUMMARY
All functions can be carried out in the user account, without
logging into a special TRANSP account:

<tokamak_id> is a 3 or 4 character tokamak id, e.g. "TFTR"
<run_id> is a TRANSP run id, e.g. "12345A01".

SET_TOKAMAK <tokamak_id> -- set the default tokamak.
  Use SET_TOKAMAK to avoid having to type in the tokamak_id
  argument to various commands.  If you always work on data
  from the same tokamak, put a $ SET_TOKAMAK command in your
  LOGIN.COM.

TRDAT -- check input data
  (a)  set default to the directory containing the run namelist
  (b)  $ TRDAT ...

tr_start <runid>  -- Start a run by creating an Input Tree in MDSplus
      
tr_send  <runid> [trdat]  -- submit the run for execution

tr_cleanup <runid> <tok> -- queue a request to delete a run
  --> The decision is final. The run is destroyed and cannot be restarted.
      If the run is still active, it will be aborted.
  
tr_look --  queue job to look at output of run that has not completed
  (a) tr_look <runid> [archive]
  (b) when monitor shows available, examine it with rplot

To Monitor a Run see:
   http://w3.pppl.gov/transp/transpgrid_monitor

For Details see: 
  PPPL Users -- http://w3.pppl.gov/transp/pppl.html
  Grid Users -- http://w3.pppl.gov/transp/production.html


4 SET_TOKAMAK
This command creates a DCL symbol and logical name defining the 
"default tokamak" for many TRANSP commands.  By using this
command, the user can avoid having to type in the tokamak id
when using PRTRAN, TRDAT, ENQUEUE/DEQUEUE, TR_LOOK, TR_ARCHIVE,
TR_CLEANUP, or TR_HALT.

Use of $ SET_TOKAMAK without arguments causes the current default
tokamak setting (if any) to be displayed.  The form

    $ SET_TOKAMAK NONE

causes the default setting to be erased, in which case the user 
will (once again) have to supply PRTRAN, etc., with a tokamak
specification on each occasion of use.

The command form

    $ SET_TOKAMAK <tokamak_id>

changes the currently set default tokamak.  The validity of the
argument is checked.

4 TRDAT
The TRDAT program reads the input UFILES for a TRANSP run and writes
an intermediate file (the Unified Physics File or UPF) which is read
by TRANSP itself.

Normally, TRDAT runs automatically in the course of a TRANSP batch
job.

However, when setting up a TRANSP run on new data, it is usually
desirable to run TRDAT interactively at least once to check the
data before trying to run the TRANSP batch job.  This method
catches many mistakes in the input data with the least amount of
inconvenience.

To interactively run TRDAT on a run TFTR.84 12345A01, follow these
steps:

(a)  set default to the directory containing the TRANSP namelist.

(b)  $ TRDAT

and give the tokamak and TRANSP run id when prompted.

TRDAT will read the Ufiles indicated in the namelist, and may make
some comments about the data.  If TRDAT detects a serious error with
the data, it will complain.  Typical errors are:  Ufile not found, 
Ufile units not correct, Ufile data spatial range not consistent 
with the plasma coverage specification in the namelist.

TRDAT will complain about certain namelist errors, such as a switch
setting says "read the so-and-so data" but a Ufile for the so-and-so
data is not specified.  See the sections on TRDAT under
$ TRANSPHELP OPERATIONS NAMELIST TRDAT ...

When all of the data has been processed, TRDAT gives a menu of
options, the most important of which are:

  enter "1" to plot scalar functions of time 
  enter "2" to plot profile functions of time.

Use these options and the graphics subroutines to carefully examine
your input data, as TRANSP sees it.  Note that TRDAT may have
performed units conversions on your data if your namelist allows
this by setting LFIXUP=2 (for more info, see namelist documentation).

If your data includes "events", e.g. pellets, be very careful that
TRDAT has cleanly extrapolated your data to discontinuous breaks
at the event time(s).  It is especially critical that the Zeff or
visible bremsstrahlung data and the electron density data be well
handled at pellet times; failure to do so will often crash TRANSP
if the data error is not caught in advance.

If the pellet breaks are not clean, it is generally necessary
either to improve the input Ufile, or else specify a wider 
"safety interval" around the event time in the namelist...  New
users should probably seek help from an experienced user when
trying to model pellet or sawteeth events in TRANSP for the first
time.

If your data passes inspection in TRDAT, then, you may queue the
run for execution with tr_send.

5 TRDAT_options
If you know what you are doing, you may skip data checks in trdat by setting
environment variables.
(1) If you want to extract Ufiles from mdsplus via
     SCLREQ(1)='$UFCOPY'
    but not all files are presen you can prevent trdat from aborting by
    defining environment variable MDS_NOSTOP

(2) If you have bad data and want to use only the good part via setting 
    appropriate timedependent Namelist switches but trdat aborts: 
    Define environment variable TRDAT_NOSTOP

CAVEAT: be sure to unset it

4 OBSOLETE
SET_SCDIR <directory_name> -- set the default directory you
  use for TRANSP namelist and job control files -- only 
  necessary if you use a laser archived directory where 
  the system can move the files from one disk (write-cache)
  to another (read-cache).  SET_SCDIR now supports defining
  a different directory for each tokamak.

PRTRAN -- set up a TRANSP batch job.
  (a)  set default to the directory containing the run namelist
  (b)  $ PRTRAN ...

ENQUEUE -- queue the run for eventual execution
  (a)  set default to the directory containing the run namelist
  (b)  $ ENQUEUE ...

DEQUEUE -- dequeue a run that has not yet started execution
  $ DEQUEUE <tokamak_id> <run_id>

RMONITOR -- check status of TRANSP runs in queue and executing
  $ RMONITOR ...

TR_LOOK -- queue job to look at output of run that has not completed
  (a) $ TR_LOOK <tokamak_id> <run_id>
  (b) when plot files <run_id>MF.PLN and <run_id>NF.PLN appear in
      WORK:[TRANSP.<tokamak_id>], examine them with $ RPLOT

TR_HALT -- queue a request to halt (abort) a running TRANSP job
  $ TR_HALT <tokamak_id> <run_id>

TR_ARCHIVE -- queue a request to archive a partial run:
  $ TR_ARCHIVE <tokamak_id> <run_id>
  --> The decision is final.  The run cannot be restarted.  If the
      run is running when the command is issued, it will be aborted.

TR_CLEANUP -- queue a request to delete a run:
  $ TR_CLEANUP <tokamak_id> <run_id>
  --> The decision is final.  The run is destroyed and
      cannot be restarted.
5 SET_SCDIR
This command creates a DCL symbol naming the directory containing
the TRANSP namelist and job control files, used by $ ENQUEUE.

If SET_SCDIR is not invoked, $ ENQUEUE uses the current default
disk:[directory], which is usually OK.  The "disk" specification
is reduced to a physical device name, to avoid a possible
process-dependent name definition.

The problem comes in if the selected directory is backed up by
laser disk.  In this case, PPPL laser archiving software will
move the files from one disk (the write cache) to another (the
read cache).  If this happens, the TRANSP job queue manager 
will not be able to find your namelist and job control files
when it comes time to submit your job -- since they have been
moved -- unless you use the SET_SCDIR command prior to $ ENQUEUE.
You will get a mail message (see "queueing error" topic).

The argument to SET_SCDIR must have the form disk:[directory]
where the logical name for disk must be known system-wide, i.e.
it must be known by more than just the current running process,
since the name is to be used later by a TRANSP process, the
queue manager.

Example of valid usage:

  $ SET_SCDIR TR_DISK:[your_name]

INVALID example:  $ SET_SCDIR MY_UFILES (MY_UFILES is known only
to your process;  the TRANSP queue manager has no way of knowning
its value).

If you always use the same laser archived directory for TRANSP
namelists, put your $ SET_SCDIR in your LOGIN.COM.  If you change
your mind about what directory you use, then this line in your
LOGIN.COM will have to be fixed.

New Oct 1995:  you can now define multiple staging directories,
on a per tokamak basis.  For example:

  $ SET_SCDIR TFTR TR_DISK:[your_name.TFTR]
  $ SET_SCDIR PBXM TR_DISK:[your_name.PBXM]

where applicable tokamak specific directory specifications take
precedence over the default SET_SCDIR directory specification.

Too see your current settings (or get help if no settings exist)
just enter $ SET_SCDIR command without arguments.
5 PRTRAN
PRTRAN must be run once to set up the batch job control files for a
TRANSP run.  Once PRTRAN has been run, it does not have to be run
again, even if the namelist changes.

PRTRAN is a simple interactive program which accepts data needed to
set up the run batch job.

For clarity on how to run PRTRAN, let us assume that we are setting
up the run TFTR.84 12345A01 for execution.  Then:

(a)  set default to the directory containing the run namelist, i.e.
the file 12345A01TR.DAT.

(b)  $ PRTRAN ... and answer the questions:

When prompted for username, give the name people use to send MAIL
messages to you.  The TRANSP batch job will send MAIL to you upon
completion, informing you either that the run completed successfully
or that it terminated abnormally.

When prompted for tokamak, give the name of the tokamak that
produced the data to be analyzed.  You may use the DCL command
$ SET_TOKAMAK to preset this data and avoid this prompt.

When prompted for run id, give the run id, e.g. 12345A01.

[PRTRAN will read the namelist and may generate an error if there
is a problem in the namelist data].

When prompted for two digit shot-year code, give the correct value,
if PRTRAN has been unable to infer the correct value.  In this
example the correct two digit code is "84", for TFTR shot year 1984.
It is important that the correct shot year be given.  PRTRAN can
usually guess the correct shot year for TFTR runs.

When prompted for comments, give a brief description of the run.
Note that the length of the lines you type in is restricted.

When prompted for plot control file option, type "0" unless you
have taken explicit measures to set up your own plot control file.

Answer "Y" to receive MAIL notification of TRANSP run completion.

Answer the last few questions concerning disposition of hardcopy
plots produced by the TRANSP batch job.

When PRTRAN re-prompts for a (new) run id, type "Q" to quit, unless
you are setting up more than one run in a single PRTRAN session.

When done with PRTRAN, your TRANSP run is ready to be submitted.
Note, however, that PRTRAN only does the most rudimentary check
on your namelist input data.  If you are preparing a TRANSP run
on new data (never before analyzed by TRANSP), you will probably
want to use $ TRDAT to check the data before proceeding to start
the TRANSP batch job.

5 ENQUEUE_to_start_a_TRANSP_run
The ENQUEUE command is used to request execution of a TRANSP run.
ENQUEUE will not work unless $ PRTRAN has already been run.

To enqueue a new TRANSP run TFTR.84 12345A01 for execution:

(1)  set default to the directory containing the run files

(2)  $ ENQUEUE 12345A01    ! to enqueue to the first available
         or                ! machine.  Machines can be listed
     $ ENQUEUE 12345A01 *  ! using $ RMONITOR L
         or
     $ ENQUEUE 12345A01 UNIX   ! to enqueue to any UNIX machine
         or
     $ ENQUEUE 12345A01 VAX    ! enqueue to any VMS machine
         or
     $ ENQUEUE 12345A01 <node> ! to enqueue to the named node, which
                               ! can be a VMS or UNIX machine.

ENQUEUE will prompt for tokamak id -- or it may be provided in
the command line using the forms (for example):

     $ ENQUEUE TFTR 12345A01  ..or..  $ ENQUEUE 12345A01 TFTR
     $ ENQUEUE TFTR 12345A01 * ..or.. $ ENQUEUE 12345A01 TFTR *

or the tokamak id may be set using the $ SET_TOKAMAK command.

Runs which are enqueued but not yet executing each have a 
priority code associated with them.  This priority code is a 
number between 1 (low) and 9 (high).  The default priority 
is 5.  To set a non-default priority, enter a command such as

     $ ENQUEUE 12345A01 * PRIORITY 3

E.g. to set a priority of 3.  The number after the keyword 
"PRIORITY" is used as the run's priority code.  NOTE -- if
you specify a priority greater than 5, ENQUEUE will require
you to type in comments giving a reason for the high priority
run request.  These comments are visible to other users via
the $ RMONITOR command.  You may also voluntarily ask to be
prompted for comments by putting the COMMENT keyword in your 
ENQUEUE command line, as in

     $ ENQUEUE 12345A01 * PRIORITY 3 COMMENT

As machines become available, the TRANSP queue manager software
will submit runs for execution.  High priority runs are 
submitted before low priority runs; in the case of ties, runs 
are submitted in the order in which the were originally 
enqueued.  The queue manager (the TRMONITOR job in the H_NORM 
batch queue) runs about once per hour to submit runs for 
execution on free processors.

Quick help is available on $ ENQUEUE by simply typing the
command name

     $ ENQUEUE

with no arguments.
6 Queues
ENQUEUE causes your TRANSP run to be entered into a logical queue.
Each queue points at one or more machines (VAX or UNIX).  Your run
will be submitted when a machine of the right type is available
and when (based on priority and/or age) your run is at the head
of the queue.

There are five types of queues:

  generic queue -- points at all machines.  Selected by default or
    by using the "*" argument to ENQUEUE.
  generic UNIX queue -- points at all UNIX machines.  Selected by
    using the "UNIX" argument to ENQUEUE.
  generic VAX queue -- points at all VMS machines (including alpha
    machines).  Selected by using the "VAX" argument to ENQUEUE.
  specific UNIX queue -- points at a specific UNIX machine. 
    selected by naming the machine in the ENQUEUE command arguments.
  specific VAX queue -- points at a specific VMS machine.
    selected by naming the machine in the ENQUEUE command arguments.

Note that machine-specific queues no longer have priority over 
generic queues (specific queue priority was deleted in 1994,
superseded by the DO_CONFIG machine reservation mechanism).

TRANSP run queueing is controlled by a configuration database, which
is accessible from the TRANSP account only.  To access this, login
as TRANSP and do

   $ DO_CONFIG

From this program, it is possible to interactively define the sets
of VAX and UNIX machines accessible to TRANSP and the machine
properties (e.g. a multiprocessor can be set up to accept two 
TRANSP runs running in parallel).

The availability and relative capacities of machines are set in
the CONFIG program.  Also, specific machines can be "reserved", 
which means that runs in the generic queues only reach that machine
if the run is either owned by the right person or analyzes data 
from the right tokamak.  Example:  machine XYZ was purchased 
with money from the MEGA tokamak, so only MEGA TRANSP runs are 
queued to XYZ.
5 DEQUEUE
If an ENQUEUE'd TRANSP run has not yet started executing, it may
be de-queued with the $ DEQUEUE command.  Note that unlike the 
$ ENQUEUE command, $ DEQUEUE requires two arguments:  the run id
and the tokamak.

To use $ DEQUEUE to de-queue TRANSP run TFTR 12345A01, do the
following:

     $ DEQUEUE TFTR 12345A01

or alternatively, 

     $ SET_TOKAMAK TFTR
     $ DEQUEUE 12345A01

Note that if the job has commenced execution, the $ DEQUEUE command
will have no effect.
5 RMONITOR 
Use the $ RMONITOR command to monitor the status of TRANSP runs,
whether queued or executing.  You do not have to login as TRANSP
to use the $ RMONITOR command, provided you have followed the
instructions in the PPPL system HELP, $ HELP TRANSP, to set
up your account to have access to TRANSP output.

With $ RMONITOR you may display either the list of currently
available computing nodes, or the list of queued and executing
TRANSP runs.  To see only the list of runs, use the command

    $ RMONITOR D Q

which inserts the command options "D Q" into the typeahead stream
for the RMONITOR program.

Enqueue'd runs are listed showing their dates and enqueue priorities.

Executing runs show what part of the TRANSP batch job is executing,
e.g. pre/post processing or "executing" for TRANSP itself.  If
available, the time of last restart is displayed, which indicates
how far into the simulation TRANSP has progressed.

RMONITOR will show all TRANSP runs:  runs set up by you and by 
other users.  
5 TR_LOOK
TR_LOOK -- queue job to look at output of run that has not completed
  (a) $ TR_LOOK <tokamak_id> <run_id>
      If $ SET_TOKAMAK is used, <tokamak_id> may be omitted.
  (b) when plot files <run_id>MF.PLN and <run_id>NF.PLN appear in
      WORK:[TRANSP.<tokamak_id>], examine them with $ RPLOT

The TR_LOOK command asks the TRANSP queue manager to create a
"TRLOOK" job to translate the output files of a run *while it is
still running*, allowing the user to have a peek.  CAUTION -- one
or more hours of delay can be expected in creating the binary
version of the output files which can be examined using the 
$ RPLOT plotting code.

When running RPLOT be sure to specify the WORK disk and the 
appropriate tokamak subdirectory.  These temporary files are
written in the WORK directory, not a RUNDATA directory; RUNDATA
is reserved for completed, archived runs.
5 TR_HALT
TR_HALT -- queue a request to halt (abort) a running TRANSP job
  $ TR_HALT <tokamak_id> <run_id>

If $ SET_TOKAMAK is used, <tokamak_id> may be omitted.

This causes a run to be halted (aborted).  RMONITOR will show the
run status as "stopped by user".  If there is sufficient disk
space, the machine where the run was running becomes available
for another TRANSP run.  to restart the run later, 
  (a) if it was running on the VAX, do
      $ ENQUEUE <tokamak_id> <run_id> RS
  (b) if on a workstation, get the workstation id <ws_id> from the
      RMONITOR display, and then
      $ ENQUEUE <tokamak_id> <run_id> RS <ws_id>

Note that $ ENQUEUE is the only way to restart the run -- so, the
halted run loses its queue position.  Halted runs use up a lot of
disk space, so $ TR_HALT should not be employed routinely.

Only runs "owned by you" can be halted by you.
5 TR_ARCHIVE
TR_ARCHIVE -- queue a request to archive a partial run:
  $ TR_ARCHIVE <tokamak_id> <run_id>
  --> The decision is final.  The run cannot be restarted.  If the
      run is running when the command is issued, it will be aborted.

If $ SET_TOKAMAK is used, the argument <tokamak_id> may be omitted.

The run is aborted if it is still running.  Then it is archived as
if it had completed successfully.

Only runs "owned by you" can be archived by you.
5 TR_CLEANUP
TR_CLEANUP -- queue a request to delete a run:
  $ TR_CLEANUP <tokamak_id> <run_id>
  --> The decision is final.  The run is destroyed and
      cannot be restarted.

If $ SET_TOKAMAK is used, the argument <tokamak_id> may be omitted.

The run is aborted if it is still running.  Then, all traces of
the run are removed from TRANSP VAX and workstation disks.  This
frees up the disk space for use by other runs.

Only runs "owned by you" can be deleted by you.

4 Restartability
All TRANSP runs are RESTARTable by means of a RESTART file which 
contains an image of TRANSP COMMON blocks at the time of last output.
It is important to understand that jobs restart from the point of
last output.  Any calculation between the last output and "crash" or
unauthorized termination is redone.  The run's random number seed is
in TRANSP COMMON; therefore Monte-Carlo run restarts will produce
exactly the same result as if no restart had been necessary 
(unless the code is modified and relinked).

By means of the TRANSP namelist control MRSTRT, TRANSP can be caused
to write restart records less frequently.  I.e MRSTRT=-5 causes a
restart record to be written once for every 5 minutes of cpu time
consumed.  The advantage of this is some speed-up of execution 
through reduced i/o; the disadvantage is greater lost cpu time 
in case of system failure, and less convenience debugging in 
case of code failure.

The default, which is recommended, is MRSTRT=-20 on all machines.

All restart records are written just after writing an output record.
Therefore, with the setting MRSTRT=-20, more than 20 minutes of cpu
time may transpire between restart record writes, if the code does
not get to write output frequently.

Setting MRSTRT=+10 causes restart writes once every 10th output time.

Note: if ELVIS runtime monitoring is enabled, MRSTRT=-1 is enforced:
monitoring updates will be send, and restart records written, once
per minute.  This is a useful feature for TRANSP production systems
with jobs running on local hard drives such that restart file i/o
is fast.

4 Error_recovery
It is not all that difficult to cause TRANSP to fail.  Typical
reasons for failure of a TRANSP run are:

  *  errors in the namelist
  *  errors or inconsistencies in the input physics data
  *  bugs in the TRANSP code
  *  physics data explores a new operating regime which TRANSP
is not equipped to handle.

The challenge, of course, is to determine the cause more precisely.
The available methods for meeting this challenge are (1) examine
the output of the aborted run, and (2) debug the run with a 
symbolic debugger tool.

TRANSP users can look at the output without special assistance.
If debugging is required, then a TRANSP specialist (someone with
the password to TRANSP and workstation accounts) may be needed.

5 Run_Output
The first place to look for clues as to the cause of the failure
of a TRANSP run is in the run log file. 

For production runs, the "tail" of all logs are on the Web:
	http://w3.pppl.gov/transp/log/

If for example the run is TFTR.89 12345A01, the log file will be
in directory TFTR
	12345A0_tr.tail

For developers, the log and all output would be in
	$WORKDIR/<tok>

For production runs all output of a crashed run is in
	$RESULTDIR/<tok>/<runid> 
    
When TRANSP crashes, it occasionally manages to put a clear 
message into the log file indicating the cause.  At other times
it is necessary to look into the run's various *.tmp files.

These are text files which may be examined with text editors.
Usually the relevant messages are at or near the end of the
file.

Finally, if the run has progressed far enough to have plot
output, this, too, may be examined.

For production runs, output of failed runs is in MDSplus
	Server = _transpgrid.pppl.gov (grid user)
	Server = transpgrid.pppl.gov  (non-grid user)
	Tree = trlook_<tok>

e.g.: rplot t s _transpgrid.pppl.gov t trlook_tftr q 12345A01 

Some output can also be examined via Elvis on the Web.
	See http://w3.pppl.gov/transp/#Runs

5 Common_Problems
The typical TRANSP crash carries the message "DT.LT.DTMINT".
This says that a solved-for quantity, e.g. ion temperature, is
"changing too rapidly", so that errors are above the acceptance
criterion even when TRANSP uses the shortest possible timestep.

Such an error often indicates a problem in the input data, 
especially if it occurs in close proximity to an "event" such
as pellet injection.  The input data (especially, electron
density, and Zeff or Visible Bremsstrahlung) should be 
examined closely at the crash time.

When TRANSP crashes with DT.LT.DTMINT, the run message file
contains output showing the various terms in the equation
precipitating the crash.  Usually one term can be identified
as driving the crash.  This is a major clue.

Sometimes the code crashes with the message

       ==> THE ION TEMPERATURE WENT NEGATIVE

This occurs most commonly in the edge region and generally 
indicates a problem with the input data.  Either the edge
density is too low, or, a very rapid upward spike in Zeff
is causing the entire hydrogenic thermal plasma to be 
pumped out on a short timescale.  The negative temperature
occurs because of instabilities in the implicit solution 
for ion temperature which appear when the ratio of
convective flow over density (i.e.: cross-flux-surface
velocity) becomes very large.

Another problem that can cause negative ion temperatures
in the edge region occurs in rotation modeling.  If input
data implies an increase in plasma angular momentum, but
there is no corresponding torque (i.e. the beams have
not yet been turned on), the result can be bizarre
consequences in the TRANSP energy model that follow from
negative angular momentum diffusivity.  This would be an
artifact from a data problem.  The problem can be fixed
by making sure that rotation is near zero before the
neutral beams come on (by manipulating the angular
velocity input data with a program such as CONCAT).

Sometimes, the code crashes with the message that a
thermal ion specie density has gone negative.  This 
usually means problems with the electron density data:
the classically modeled fast ion density exceeds the
electron density somewhere in the profile.  Such a
problem can occur e.g. if the electron density measure-
ment does not have the spatial resolution to see a 
highly peaked profile such as can occur with intense
neutral beam injection into a low density target.  The
only solution (usually) is to improve the electron
density data.  Of course it may also be that fast ion 
populations are being modified by strong non-classical 
effects, but, if this is true, then TRANSP probably 
cannot be used to model the experiment.

  **(dmcApr16 -- end of section to be updated)**

2 Code_info
This information is of interest only to those that have access to a
copy of the TRANSP source-- typically, developers.  Because these 
documents are old, there are namy references to the VMS logical 
designator "SOURCE:".  On unix systems this refers to 

  $TRANSPROOT/codesys/source

and also, all source element files are in lowercase, except for 
"INCLUDE" files in $TRANSPROOT/codesys/source/inclshare

3 Preprocessors
(for TRANSP use only)
TRDAT - read UFILEs, write temporary Unified Physics File (UPF) to be
        read back in by TRANSP.  interactive or batch

PLABEL - generate plot label/map file nnnnTF.PLN and automated 
        documentation section of nnnnTR.INF file.  batch.

3 Postprocessors
Available to TRANSP only:
POPLT2 - translate ascii temporary plot output data to binary direct
        access data; check consistency of data file and label file.
        batch.

Available to all users:
RPLOT -  plot TRANSP output data.  interactive or batch. 

2 Maintenance

Warning:
  ---> this section is old; much VMS specific information no longer
       applies.  This section has not been updated for a long time.

Basic information:  TRANSP is a 1d time dependent analysis code for
tokamaks.  It uses numeric techniques to solve partial differential 
equations in time and space to model tokamak experiments, using as 
constraints as much actual measured experimental data as possible.

The organization of the code derives from the old OLYMPUS structure.
Many subroutines share and update the same set of COMMON blocks.  The
COMMON blocks contain a description of the current "state" of the 
tokamak plasma and enough information to advance this model "state"
in time.

TRANSP uses FORTRAN **code generators** and OLYMPUS variable naming
conventions to preserve the integrity of COMMON and provide convenient
means of modification and upgrade.  The basic procedure for changing
TRANSP COMMON, RPLOT plotting output, or TRDAT Ufiles input is:

  1.  modify a specification file, a special TRANSP source file
      (see TRANSP$:[DOC]CMSMMS.MEM on modifying TRANSP sources 
      and code in general):

      a.  modify PORT.FOR to revise TRANSP COMMON BLOCK specs
      b.  modify PLOTGEN.I to revise TRANSP plot output specs
      c.  modify TRDATGEN.SPEC to revise TRANSP Ufile input specs

  2.  submit a batch job for automatic regeneration of code and 
      recompilation of affected routines:

      $ SUBMIT ALLCOM:BUILD to change TRANSP COMMON and rebuild 
        subroutine libraries and programs.
      $ SUBMIT ALLCOM:PLOTGEN to change TRANSP plot data output
        and update affected objects, subroutine libraries, and 
        programs.
      $ SUBMIT ALLCOM:TRDATGEN to modify TRDAT physics data
        acquisition and update all affected objects, subroutine
        libraries and programs.  CAUTION-- if a new data type
        is added, TRDATGEN will run BUILD and PLOTGEN as 
        subprocedures!

3 Special_files
    "**" denotes GENERATED FORTRAN code.  DO NOT EDIT GENERATED CODE!
instead, fix the specification file and/or fix and/or run the proper 
code generator.  Uppercase: VMS files...

  ====================
    PORT.FOR    TRANSP automatic documentation and OLYMPUS COMMON block
                specification file.  EDIT specification section, NOT 
                documentation section!  Processed by BUILD batch job.

    TRANS.COM   ** generated COMMON blocks for TRANS.COM
    TRNGEN.FOR  ** generated utility subroutines for TRANSP.  Includes
                control namelist read, physics data i/o, restart/crash
                record i/o subroutines.

  ====================
    PLOTGEN.I   TRANSP RPLOT plotting output definitions.  Plot 
                specification language defined by the PLTRGN program.
                Processed by PLOTGEN batch job.

    MFILEX.F90  ** another profile plot output subroutine for TRANSP
                   modifiable template file (template MFILE7.F00)
    MF_%%%B.F90 ** specific profile output routines
    NFILEX.F90  ** scalar plot output subroutine (template NFILE7.F00)
    NF_%%%B.FOR ** specific scalar output routines
    TFILSN.F90  ** plot map/label generator (template TFILS7.F00)
    TF_%%%B.F90 ** specific data label generator routines
    PSWITCH.F90 ** subroutine for selecting plot output
    PS_%%%B.F90 ** specific switching routines

  ====================
    TRDATGEN.SPEC - TRDAT UFILE INPUT SPECIFICATIONS.  This file
       defines the expected independent coordinates, time series
       data, and profile data to be read in as input for TRANSP
       runs.  Physical units and units conversion tables are
       defined.  Data type specific options are specified (e.g.
       whether a given input data type can show a "discontinuous" 
       change in the event of pellet injection).

       NOTE that the generator input files PORT.FOR and PLOTGEN.I
       can be modified by the TRDATGEN generator procedure!

       NOTE that the TRDATGEN output files are "partially generated";
       code not lying between comment lines "C=>TRDATGEN+" and
       "C=>TRDATGEN-" may be modified directly without running the
       TRDATGEN program.

    PORT.FOR    ** TRANSP COMMON specs to support Ufile data input
    PLOTGEN.I   ** TRANSP plot output specs modified to support
                   output of flux surface mapping comparison on
                   input profile Ufiles.

    TRDATA.BLK  ** TRDAT COMMON blocks

    CKFREE.FOR  ** check TRDAT memory buffer for sufficient free space
    DDATA.FOR   ** declare and read TRDAT namelist
    DGRAF1.FOR  ** plot 1d (time series) data acquired by TRDAT
    DGRAF2.FOR  ** plot 2d (profile) data acquired by TRDAT
    DPRSET.FOR  ** preset TRDAT namelist defaults and constants
    MAKSYM.FOR  ** presymmetrize TRANSP profile input data
    PLPARM.FOR  ** interpolate time series data for TRDAT and TRANSP
    PRESET.FOR  ** preset TRDAT-related TRANSP namelist defaults
    PROFIN.FOR  ** interpolate and map profile input data for TRANSP
    SETD1D.FOR  ** process time series data
    SETD2D.FOR  ** process profile data
    TESTMAP.FOR ** TRDAT subroutine for testing TRANSP profile maps
    TR2INI.FOR  ** presymmetrization setup routine for TRANSP
    TRCHK2.FOR  ** check profile mapping/symmetrization controls
    TRFILS.FOR  ** generate list of input data for TR.INF file
3 Generator_Caveats
The power of TRANSP generators should not be overestimated.  The
generators merely create data structures or interfaces; it is still
up to the programmer to write code to make effective use of these
structures.

For example, TRDATGEN generates a subroutine PROFIN which can be
used in TRANSP to obtain profile information at a specified time.
But TRDATGEN does NOT generate the call to PROFIN nor does it
make any recommendation about when PROFIN should be called or
what to do with the data it returns!  Making these determinations
requires actual human intelligence, and usually, some knowledge
of the inner workings of TRANSP.
3 Variable_name_convention
    ALL TRANSP routines which INCLUDE 'TRCOM' i.e. which use TRANSP
COMMON blocks should adhere to this convention to prevent inadvertant
corruption of the COMMON blocks.

    The FIRST LETTER in the name of all variables and arrays should
convey the following information:
  1st letter          data type                   location
   A--H                REAL or COMPLEX             TRANSP COMMON
   I--K                INTEGER or LOGICAL          NOT in TRANSP COMMON
   L--N                INTEGER or LOGICAL          TRANSP COMMON
   O--Y                REAL or COMPLEX             TRANSP COMMON
   Z                   REAL or COMPLEX             NOT in TRANSP COMMON

    Thus ALL VARIABLES which are LOCAL to a subroutine or in a COMMON
block other than TRANSP COMMON should start with letters I,J,K or Z.

    No naming convention applies to routines which are linked with TRANSP
but do not use the common blocks.  However, it may be desirable to use 
the convention in any case for ease of future integration of the sub-
routine into the COMMON structure.

***GENERAL RESTRICTIONS: ***
    Because TRANSP code needs to be portable, only ALPHANUMERIC characters
may appear in a variable name and non-TRANSP names may not be greater 
than 8 CHARACTERS LONG.  Also, avoid non standard control structures
such as DO -- ENDDO:  these are not portable.

    See info on LISMAK and SUPSUB for means of perpetrating wholesale
name changes on codes.
3 LISMAK
LISMAK is a program for making alphabetized lists of symbols in FORTRAN
programs.  These lists are written in standard format files and can be
manipulated (e.g. lists can be joined, intersections calculated, etc.).
The lists contain two columns and can be manipulated with an editor to
form a list of name changes which LISMAK can read back in and apply to
FORTRAN sources.

This is a good way to "OLYMPUSize" the variable naming conventions in
new "foreign" source code.

LISMAK is well oriented to making large numbers of name changes in a
small number of source files.  For making 1 or 2 name changes in large
numbers of files, see SUPSUB.

LISMAK is old and we think pretty thoroughly debugged.
See miscellaneous klugey HELP info in lismak.hlp, doc area.
3 SUPSUB

$ SUPSUB <filename> <from string> <to string> 

will cause all files <filename> (wildcards ok) which contain occurrances
of <from string> to be editted with EDT and a substitute command 
executed which substitutes <to string> for <from string> everywhere.

More documentation of SUPSUB exists on disk in files 
TRANSP$:[DOC]SUPSUB.*
3 SELCOMP

$ SELCOMP [TRANSP.WRK]*.FOR TRCOM COMP

will cause all files [TRANSP.WRK]*.FOR which INCLUDE the file
TRCOM (logical name for TRANSP COMMON INCLUDE file) to be recompiled 
with the $ COMP command.

check out this DCL hack.  This may be useful in certain debugging
situations, but, its functionality has generally been superseded by
the CMSMMS system.  See TRANSP$:[DOC]CMSMMS.DOC.
3 COMMON
  To modify TRANSP COMMON blocks:
    1.  Edit the TRANSP source element PORT.FOR.  ONLY lines which start 
with the letter combination "CP" are accepted as COMMON specification 
input.  If you have never worked with PORT.FOR before, PRINT the existing
versions of PORT.FOR and TRANS.COM and TRNGEN.FOR, and learn the meanings
of control symbols in PORT.FOR as reflected in the generated output files
TRANS.COM and TRNGEN.FOR.
    hints:  a)  do not use TABs in PORT.FOR !!!
            b)  "*" is a symbol for namelist input
            c)  understand and use "symbolic array dimensions".

    2.  $ SUBMIT ALLCOM:BUILD -- the batch job requires approx. 4 hrs of 
VAX-8600 time, mostly to recompile all routines which use TRANSP COMMON.
3 Plot_output
  To modify TRANSP plotting output:
    1.  Edit PLOTGEN.I in the [TRANSP] area.  ONLY lines starting with
the character combinations "C%", "C&", "C$", "C*" and "C#" are processed
as plot specification lines.  If you have never worked with PLOTGEN.I, 
LEARN the plot specification language.  Suggestions for this:
      a)  Know how to use RPLOT to examine the plotting output of TRANSP
runs;  be familiar with the contents of the output files of existing 
runs.
      b)  Note the relationship between RPLOT and TRANSP common.  
The plot system works by writing information from common to an output 
file at designated plot output times.  However, once the data has been
written the system is no longer dependent on TRANSP common (therefore
TRANSP common can change without jeopardizing access to old run data).
The purpose of the plot specification language is to identify what 
pieces of COMMON to write, specify label and physical units for the 
information, and to give an RPLOT key name for the information.
The plot system also provides for logical switching of output (e.g. no
beam code outputs if there are no beams in a run), and grouping of
information (e.g. assembly of ion power balance terms into a single
ion power balance "multigraph").
      c)  Study the existing plot specification file PLOTGEN.I and 
note how the output definitions there are mapped in the output file of
an actual run.
    2.  Test changes to PLOTGEN.I by running 
        PYTHON SOURCE_PLOTGEN:PLOTGEN.PY PLOTGEN.I
in a temporary working directory, and specify your modified copy of 
PLOTGEN.I as input.  If PLOTGEN runs without error then PLOTGEN.I is 
syntactically correct.  Note "DUPLICATE NAME" warnings may be ignored 
if the logic encoded in PLOTGEN.I assures that only one name definition 
will be selected in an actual TRANSP run (there are instances of this).
    3.  After making changes to PLOTGEN.I and returning it to the
SOURCE area,

          $ SUBMIT ALLCOM:PLOTGEN

to run the TRANSP plot output code generator and rebuild affected
parts of the system.  Check carefully that the PLOTGEN batch job
runs correctly!  Errors in PLOTGEN.I can cause TRANSP to be
left in an unusable state.
3  TRDAT
Basic maintenance of TRDAT is carried out using the TRDATGEN code
generator, via the batch procedure ALLCOM:TRDATGEN.COM.  The
method is

    (1)  modify the specifications file SOURCE:TRDATGEN.SPEC
    (2)  run the batch job ALLCOM:TRDATGEN.COM

TRDATGEN runs a "C" program to analyze TRDATGEN.SPEC, which is 
heavily commented and has a flexible format.  The maintener should
study the existing TRDATGEN.SPEC before trying any changes.
4 TRDATGEN.SPEC
The file SOURCE:TRDATGEN.SPEC contain specifications which define
Ufile input data to TRDAT and hence to TRANSP.

Although the format of this file is flexible, the maintainer 
should study it before attempting changes.

This study should confirm the following general observations:

  -> comments start with the character "!" and end with end-of-line
  -> outside of comments, wherever blanks appear, additional blanks 
     or end-of-lines may be inserted without affecting the meaning
     of specifications.
  -> data types and independent coordinates are identified by
     "trigraphs" or three letter names, in the form

        *<trigraph>(<dependencies>)
                 { '<max_20_char_label>', '<max_10_char_units>'}

     as in the examples

        *TIM       { 'time',     'seconds' }
        *CUR(TIM)  { 'plasma_current',      'amps' }
        *TI2(TIM,RAD)   { 'ion temperature',      'ev' }
        *SIM(TIM,RAD,-) { 'impurity species', 'n/cm**3' }

     The "*" character signals the start of a new data type
     specifier.

  -> data type specifications are modified by switches which have
     various formats

        /<switch_name>
        /<switch_name> = <value>
        /<switch_name> = { <list of values> }
4 Units_conversion
TRANSP input data units conventions are expressed in TRDATGEN.SPEC.

Units conversion factors may be set up or modified for any data type 
or independent coordinate.  This is done by using the switch

        /conversion_table = { <conversion table entries> ... }

under the appropriate data type or independent coordinate specifier.

There are two types of conversion table entries.  One type gives
just a label-- this identifies acceptable synonyms for the standard
units, e.g. 'S' or 'SEC' for 'SECONDS'.  The second type gives a
label followed by a conversion factor, e.g. " 'MS' * 0.001 ", 
which indicates a label for data that may be converted to the 
standard units by multiplying the data by the factor 0.001.

In order to add support for a "different" Ufile units label for a
given data type, it is necessary only to modify the conversion table
for the data type and run the TRDATGEN generator.  Note-- if this
is the only change, TRDATGEN will run quickly.  The TRANSP COMMON
and output generator jobs BUILD and PLOTGEN will not run under
TRDATGEN unless the TRDATGEN changes are extensive enough to 
actually require TRANSP COMMON and output changes, and this is not
the case for modifications to units conversion tables.

If a given data type has no conversion_table entry, then, neither
units checking nor conversion is supported for that data type (but
the data type independent coordinate label will still be checked).
If a conversion table is present, then input Ufiles of that data 
type are expected to have units labeling matching entries in the 
conversion tables both for the data type itself as well as for its
independent coordinates.  The matching algorithm is not sensitive
to case or to "punctuation" -- only alphanumeric characters are
checked, so that the labels "CM" and "Cm." would appear equivalent
to the label matching code.

A short example of a conversion table is as follows:

  /conversion_table = 
      {
         'EV'
         'KEV' * 1000.0
      }

For the affected data type, this means that the Ufile dependent
data label is REQUIRED to be either "EV" or "KEV" (or the 
equivalent, with lower case and punctuation allowed); if the
data label is "KEV" it may be multiplied by 1000.0 to bring it
in conformance with the TRANSP convention that temperatures are
expressed in "EV".

REMINDER -- the TRDAT global namelist switch LFIXUP can be used to 
control units conversion code behaviour.  See 
    TRANSPHELP OPER NAMELIST TRDAT
4 Independent_coordinates
TRDATGEN expects a fixed set of independent coordinates to be
defined.  This set cannot be changed unless the TRDATGEN code
is also changed.  Therefore, no attempt should be made to add
independent coordinates except by someone intimately familiar
with the innards of TRDATGEN and TRDAT.  For advice-- consult
D. McCune.

The following independent coordinates are defined:

TIM -- time                    RAD -- radius
FRQ -- ECE frequency           XXX -- generic

Time-series data are identified by the fact that TIM is the only
specified independent coordinate.  Profile data are identified by
the fact that TIM and some other coordinate are specified; note
that TIM is always specified first.  The generic XXX is used to
identify a generic non-temporal X coordinate such as the channel
index used in the neutral beam Ufile, or the moment index in the
R and Y moments boundary Ufiles.  3D profile data are identified
by the prescense of three axis in the trigraph definition.  TIM
must be the first of the three axes.
4 Adding_data_types
To add a new type of data to be read in by TRANSP, the first
step is to define the data type in TRDATGEN.SPEC and run the
ALLCOM:TRDATGEN.COM batch job.

A unique three character data type name must be selected.  For
clarity suppose the selected name is "XYZ".  Then, running the
generator will create a new version of TRDAT which includes in
its namelist the input variables PREXYZ and EXTXYZ for naming
the Ufile containing the XYZ data.  If appropriate additional
XYZ specific namelist controls will also be created to control
treatment of data in the vicinity of sawtooth/pellet events,
and the like.  For details of what is available, see the
description of the TRDAT namelist.
4 Time_series_data_add
A specification in TRDATGEN.SPEC of the form

  *XYZ(TIM)  { 'The XYZ data', 'grommets' }

tells TRDAT and TRANSP to expect input of time series data from
a Ufile, which data can be described as "The XYZ data" with 
physical units of "grommets".

The specification may be refined by setting various switch
definitions.  See the section UNITS_CONVERSION for the
description of the /conversion_table switch.  For many cases
this will be the only switch needed.  However, the applicability
of the switch /event_discontinuity should be weighed.  The
effect of the presence or absence of the /xdat switch should
also be considered, since this determines the name of the
TRANSP COMMON REAL variable to which the time series data will
be interpolated in TRANSP.

Here is a complete list of available switches:

  /priority               ! default -- false

this means this data should be read ahead of data for which the
priority switch is not set.  This is desirable e.g. if there is
special code to "renormalize" one type of data which depends on
already having read a second type of data.  The second type
should have its /priority switch set.  Example of use:  the
interpretation of sign for diamagnetic flux data "DFL" depends
on the sign of the toroidal field data "RBZ".  /priority is
set to force "RBZ" to be read in first.

  /special_handling       ! default -- false

this means special code is to be written to read and process this
data; the generator will create namelist controls and modify 
TRDAT and TRANSP COMMON entries to accomodate the data, but
code to actually read the data and set up the COMMON entries
will NOT be generated, and is entirely up to the programmer.
Example-- sawtooth event times data "SAW".  The "SAW" Ufile
contains a list of times defining events, and its treatment
is fundamentally different than other time series data and so,
special code is required.

  /absolute_value         ! default -- false 

this means that the data is expected to be on one sign at all
times, and that this sign must be "positive".  For example, by
convention TRANSP expects plasma current CUR and toroidal field
RBZ to be positive at all times.  If in the middle of the 
analysis time the data is found to be negative, the entire
time series is multiplied by -1.0 to satisfy the convention.
The sign of the original data (+1.0 or -1.0) is saved in a
TRDAT COMMON variable for future reference-- e.g. XRNRBZ for
the RBZ data.

  /renormalize            ! default -- false

this means special code in TRDAT subroutine DRENRM1 exists to
modify the normal processing of the data.  Example of use:  the
"DFL" data is multiplied by -1.0 if the RBZ data was multiplied
by -1.0 (cf /absolute_value switch, above).  NOTE-- if this
switch is set for data type "XYZ", then the programmer must 
provide code specifically for the XYZ data type in the
subroutine DRENRM1.FOR.

  /event_discontinuity    ! default -- false

this means that the data is expected to experience "discontinuous"
changes at sawtooth and pellet events.  This flag is typically set
for quantities describing temperatures, densities, and/or Zeff; it
is typically not set for quantities related to the field or plasma
geometry.  If this flag is set, additional namelist controls are
created to allow refinement of control over data processing in
the vicinity of sawtooth and pellet events.

  /default_value = ABCD   ! default -- no default value

this is a compatibility feature for very ancient ways of using
TRANSP.  The value "ABCD" must be a REAL namelist variable in
TRANSP COMMON, which specifies a value to use for the data 
in case no Ufile data is specified.

  /xdat = WXYZ            ! default -- no XDAT value

this is a compatibility feature.  If no XDAT value is specified,
TRDATGEN creates for time series data "XYZ" the TRANSP COMMON
variable XDATXYZ.  This variable is to contain the "XYZ" data
interpolated to the "current" time via the TRANSP subroutine
PLPARM (which is in large part generated by TRDATGEN).  However,
old TRANSP had its own names for these quantities; thus the
specification "/xdat = PCUR" is used to specify that the TRANSP
COMMON variable PCUR already exists and is to be used to contain
the "CUR" data interpolated to the current time.  PCUR is used
in existing code to denote the total plasma current in amps.
4 Profile_data_add
A specification in TRDATGEN.SPEC of the form

  *ABC(TIM,RAD)  { 'The ABC data', 'grommets' }

tells TRDAT and TRANSP to expect input of profile data from
a Ufile, which data can be described as "The ABC data" with 
physical units of "grommets".  The data is expected to be
defined vs. "radius", which may incorporate all the standard
TRDAT supported options, i.e. major radius inboard side, 
major radius outboard side, major radius both sides of plasma,
or minor radius.

The specification may be refined by setting various switch
definitions.  See the section UNITS_CONVERSION for the
description of the /conversion_table switch.  For many data
types this will be the only switch needed.  However, the 
applicability of the switch /event_discontinuity should 
receive consideration.  The switches /fallback_to_timeseries
and /minimum_value should also be considered.

The following list gives the complete set of available switches:

  /special_handling       ! default -- false

this means special code is to be written to read and process this
data; the generator will create namelist controls and modify 
TRDAT and TRANSP COMMON entries to accomodate the data, but
code to actually read the data and set up the COMMON entries
will NOT be generated, and is entirely up to the programmer.
Examples-- all data vs. the "generic" X axis XXX-- moments
boundary data, neutral beam heating data, RF heating data.

  /renormalize            ! default -- false

this means special code in TRDAT subroutine DRENRM2 exists to
modify the normal processing of the data.  Example of use:  
DRENRM2 is where density profile data will be renormalized to
interferometer midplane line integral density, if the approp-
riate namelist options are set.  NOTE-- if this
switch is set for data type "ABC", then the programmer must 
provide code specifically for the ABC data type in the
subroutine DRENRM2.FOR.

  /event_discontinuity    ! default -- false

this means that the data is expected to experience "discontinuous"
changes at sawtooth and pellet events.  This flag is typically set
for quantities describing temperatures, densities, and/or Zeff; it
is typically not set for quantities related to the field or plasma
geometry.  If this flag is set, additional namelist controls are
created to allow refinement of control over data processing in
the vicinity of sawtooth and pellet events.

  /fallback_to_timeseries ! default -- fallback to fixed profile

this switch describes what to do if the input Ufile contains
only one independent coordinate.  Usually, it is assumed that
the one coordinate is space and the profile data being read has
no time dependence.  However, if /fallback_to_timeseries is set,
it is assumed that the one coordinate is time.  For example, in
the case of bolometer data "BOL", this switch is set and the
data is treated as a "wide angle" bolometer giving total power
radiated in watts rather than a profile of local power emission
in watts/cm3.

  /minimum_value = ABCD   ! default -- no default value

This switch specifies a way of setting a "minimum allowable" 
value for input data.  The value "ABCD" must be a REAL namelist 
variable in TRANSP COMMON, or "ZERO" if the minimum value desired
is 0.0.  Examples of use:  minimum values are set for temperature
and density profile inputs.

  /nx = NXABC             ! default -- no NX value

this is a compatibility feature.  If no NX value is specified
for the profile input "ABC", TRDATGEN creates the TRANSP 
namelist switch NXABC to control the resolution of the 
interpolation of the data in the spatial coordinate domain.
However, in the old code different names were used for this
namelist control.  To minimize damage to old namelists in
converting to the new code, this switch allows old names to
be retained.
4 _3D_Profile_data_add
A specification in TRDATGEN.SPEC of the form

  *ABC(TIM,RAD,-)  { 'The ABC data', 'grommets' }

tells TRDAT and TRANSP to expect input of several sets of profile 
data from several Ufiles which can be described as "The ABC data" 
with physical units of "grommets".  The data is expected to be
defined vs. "radius", which may incorporate all the standard
TRDAT supported options, i.e. major radius inboard side, 
major radius outboard side, major radius both sides of plasma,
or minor radius.  Each profile is indexed by a third generic
coordinate.  The following switch is required

  /3D = { 'IABCS', 5, 'IABCT', 30 }

This creates two new dimensions in port.for,
  IABCS=5
  IABCT=30
They indicate that there can be up to 5 Ufiles each containing
a set of several profiles and the total number of profiles
which can be input is 30.

The specification may be refined by setting various additional 
switch definitions.  These are the same as the profile switches
except the /fallback_to_timeseries switch is not allowed. 

Most of the namelist data for 3D profiles are one dimensional
arrays indexed by the set index -- one set per Ufile.  As an
example, to read in three Ufiles for the 3D SIM impurity profiles
would require the following in the TRDAT namelist,
  PRESIM = 'A', 'B', 'C'
  EXTSIM = 'IMP', 'IMP', 'IMP'
depending on the file names for the data.  

4 TRDATGEN_output
The list of FORTRAN subroutines generated by TRDATGEN is given
under TRANSPHELP MAINTENANCE SPECIAL_FILES.  In this section the
specific generated NAMELIST and COMMON variable names are given.

==================================================================
For a time series input "ABC", the following quantities are
created:

TRANSP NAMELIST
  nothing
TRANSP COMMON (but not in namelist)
  R XDATABC -- the ABC data interpolated to the current time, unless
               the name was redefined by the /XDAT switch in TRDATGEN
  I LDATABC -- address in DATBUF buffer of ABC data as processed by
               TRDAT
TRDAT NAMELIST
  C*16  PREABC -- Ufile name prefix for ABC data
  C*16  EXTABC -- Ufile name suffix for ABC data
if /event_discontinuity flag is set:
  R     XDTABC -- event extrapolation window override
  R     XTMABC(2,20) -- event extrapolation suppression intervals
  R     XTPXYZ -- Pellet extrapolation control
  R     XTSXYZ -- Sawtooth extrapolation control
TRDAT COMMON (but not in namelist)
  C*20  ABCLABEL -- nominal label for ABC data
  C*10  ABCUNITS -- nominal units for ABC data
  C*10  ABCCONL(ICTBABC) -- units conversion table units labels
  R     ABCCONV(ICTBABC) -- units conversion table conversion factors
  R     XMNABC   -- the minimum ABC data value saved
  R     XMXABC   -- the maximum ABC data value saved
  R     XRNABC   -- ABC renormalization flag

==================================================================
For a profile input "XYZ", the following quantities are
created:

TRANSP NAMELIST
  I NRIXYZ  -- Profile plasma coverage specification
  I NSYXYZ  -- Profile symmetrization option
  I NXXYZ   -- spatial resolution control on XYZ interpolation
               (no. of points) -- TRDATGEN can accept a 
               different name via the /nx switch
TRANSP COMMON (but not in namelist)
  I LFSYXYZ -- address of presymmetrized XYZ data
  I LXSYXYZ -- address of x axis for presymmetrized XYZ data
  I LSSYXYZ -- address of implied shift profile of presym data
  I LFXYZ   -- address of XYZ data as processed by TRDAT
  I LXXYZ   -- address of XYZ x axis as prepared by TRDAT
  I NXSYXYZ -- number of XYZ presymmetrized x axis points

  R SHIFXYZ(J) -- RPLOT output -- profile of inferred shifts
               output if data is symmetrized by slice and stack
  R SYMRXYZ(JRSYM) -- RPLOT output -- symmetrized, mapped data
               output to RPLOT vs. major radius
  R USYMXYZ(JRSYM) -- RPLOT output -- data interpolated without
               symmetrization, vs. major radius, to compare to
               SYMRXYZ in RPLOT.

  The outputs SYMRXYZ and USYMXYZ may be compared in RPLOT using
  the multigraph named XYZCOM.  The RPLOT names for these data
  are XYZUSE and XYZIN.

TRDAT NAMELIST
  C*16  PREXYZ -- Ufile name prefix for XYZ data
  C*16  EXTXYZ -- Ufile name suffix for XYZ data
  R     XRCXYZ -- knob to relax XYZ profile plasma coverage 
                  requirement
if /event_discontinuity flag is set:
  R     XDTXYZ -- event extrapolation window override
  R     XTMXYZ(2,20) -- event extrapolation suppression intervals
  R     XTPXYZ -- Pellet extrapolation control
  R     XTSXYZ -- Sawtooth extrapolation control
TRDAT COMMON (but not in namelist)
  C*20  XYZLABEL -- nominal label for XYZ data
  C*10  XYZUNITS -- nominal units for XYZ data
  C*10  XYZCONL(ICTBXYZ) -- units conversion table units labels
  R     XYZCONV(ICTBXYZ) -- units conversion table conversion factors
  R     XMNXYZ   -- the minimum XYZ data value saved
  R     XMXXYZ   -- the maximum XYZ data value saved
  R     XRNXYZ   -- XYZ renormalization flag
==================================================================
For a 3D profile input "XYZ" dimensioned by set parameter IS and
total parameter IT, the following quantities are created:

TRANSP NAMELIST
  I NRIXYZ(IS)  -- Profile plasma coverage specification
  I NSYXYZ(IS)  -- Profile symmetrization option
  I NXXYZ(IS)   -- spatial resolution control on XYZ interpolation
                   (no. of points) -- TRDATGEN can accept a 
                   different name via the /nx switch
TRANSP COMMON (but not in namelist)
  I LFSYXYZ(IT) -- address of presymmetrized XYZ data
  I LXSYXYZ(IS) -- address of x axis for presymmetrized XYZ data
  I LSSYXYZ(IT) -- address of implied shift profile of presym data
  I LFXYZ(IT)   -- address of XYZ data as processed by TRDAT
  I LXXYZ(IS)   -- address of XYZ x axis as prepared by TRDAT
  I NXSYXYZ(IS) -- number of XYZ presymmetrized x axis points
  I LYXYZ       -- address of third coordinate indices
  I NNXYZ       -- total number of 2d profiles
  I NITXYZ(IS)  -- map from set index to start of total index
  I NISXYZ(IT)  -- map from total index to set index
    Example:
    TotalIndex   NISXYZ           SetIndex   NITXYZ
        1          1                 1         1
        2          1                 2         3
        3          2                 3         7
        4          2
        5          2
        6          2
        7          3

  R SHIFXYZ(J,IS) -- RPLOT output -- profile of inferred shifts
               output if data is symmetrized by slice and stack
               This data is a weighted average of all the profiles
               in the set.
  R SYMRXYZ(JRSYM,IS) -- RPLOT output -- symmetrized, mapped data
               output to RPLOT vs. major radius.  This data is a
               summed composite of all the data in the set.
  R USYMXYZ(JRSYM,IS) -- RPLOT output -- data interpolated without
               symmetrization, vs. major radius, to compare to
               SYMRXYZ in RPLOT.  This data is a summed composite 
               of all the data in the set.
  R ADATXYZ(J,IS) -- absolute value of sim 2d profile data used for
               calculating SHIFXYZ(J,IS)

  The outputs SYMRXYZ and USYMXYZ may be compared in RPLOT using
  the multigraph named XYZCOM_I (I=1,IS).  The RPLOT names for 
  these data are XYZUSE_I and XYZIN_I (I=1,5).

TRDAT NAMELIST
  C*16  PREXYZ(IS) -- Ufile name prefix for XYZ data for set IS
  C*16  EXTXYZ(IS) -- Ufile name suffix for XYZ data for set IS
  R     XRCXYZ(IS) -- knob to relax XYZ profile plasma coverage 
                  requirement
if /event_discontinuity flag is set:
  R     XDTXYZ(IS) -- event extrapolation window override
  R     XTMXYZ(2,20,IS) -- event extrapolation suppression intervals
  R     XTPXYZ(IS) -- Pellet extrapolation control
  R     XTSXYZ(IS) -- Sawtooth extrapolation control

TRDAT COMMON (but not in namelist)
  C*20  XYZLABEL -- nominal label for XYZ data
  C*10  XYZUNITS -- nominal units for XYZ data
  C*10  XYZCONL(ICTBXYZ) -- units conversion table units labels
  R     XYZCONV(ICTBXYZ) -- units conversion table conversion factors
  R     XMNXYZ(IT)   -- the minimum XYZ data value saved
  R     XMXXYZ(IT)   -- the maximum XYZ data value saved
  R     XRNXYZ(IS)   -- XYZ renormalization flag

4 Left_to_programmer
The TRDATGEN generator does not entirely remove the need for hand
programming when new data types are added to TRANSP.  In this section
(still under development) some additional non-generated changes are
suggested:

  1.  CKDRNG -- modify this routine to impose a range check on the
      input data.  For example, if a temperature one could require
      the maximum temperature to be at least 50 eV...

3 TRDAT_stuff

The COMMON block containing the TRDAT namelist data is in FORTRAN
INCLUDE file SOURCE:TRDATA.BLK.  There are useful comments there.

DEFAULT VALUES of the TRDAT namelist are set in SOURCE:DPRSET.FOR
The namelist READ is performed in SOURCE:DDATA.FOR

New March 1992 -- much of TRDATA.BLK, DPRSET, DDATA, and other
TRDAT components are now generated by the TRDATGEN code generator.

The DEFAULT values for UFILEname prefixes and extensions are taken
to mean "no UFILE available".