TRANSP Introduction
	                   ===================
			  (source:trintro.doc)

			     Greg Hammett

	                     15-Jun-1988
	               Last modified:12-Feb-1991


TRANSP is a major tokamak data analysis code developed at the Princeton
Plasma Physics Laboratory. This is meant only as a short introduction to
TRANSP and as a summary of the most-used commands and procedures related
to TRANSP.  For more complete information see the online TRANSPHELP file
and the other references listed at the end of this document. 

Setting up to access TRANSP utilities and logical names
-------------------------------------------------------

You should copy the file hammett$:[com]transp_setup.com to your area,
modify all references to "hammett" to point to one of your directories,
and then call transp_setup.com from your login.com file.

To look at the results of a sample transp run, type:

$move tftr.90		! to look at a TFTR run from 1990.
$rplot 54320f03		! plot the results from shot 54320, try f03.


Preparing UFILE data for a TRANSP run
-------------------------------------

The main task is to prepare (verify, correct, and smooth) data to be
input to TRANSP.  The smoothing process is somewhat subjective, and
depends on your objectives.  For a quick run where you are mainly
interested in the equilibrium results, you can use fairly heavy
smoothing of the data and set the time steps in TRANSP to be fairly
large (50-100 msecs).  If you are interested in the details of some of
the time dependent behaviour, you will have to be more cautious about
the smoothing (and set appropriate breaks in the smoothing for sawteeth
and pellet events) and use a smaller time step in TRANSP (10-25 msecs).

Noisy data which is differentiated in TRANSP may force TRANSP to use
small internal time steps and therefore lots of computer time, and it
may lead to inferred transport coefficients which are also very noisy.

I have typically been using smoothing with dt=+-.2 seconds, and setting
internal smoothing endpoints to preserve rapid changes such as pellet
or MHD events.  I usually set the endpoint boundary conditions to zero
so that the endpoints remain fixed after the smoothing process.
See Doug's seminar notes on preparing TRANSP data for more detailed
advice on how to do the smoothing. 

You first need to spend time looking at a shot and understanding its
important features.  On TFTR, this is done with the CUPLOT program,
which is primarily used to plot TFTR "waveform" data (which includes
most of the basic TFTR diagnostics on a fairly coarse 10 msec time
grid), although it can also plot "ufile" data (another format sometimes
used for higher resolution data), though the UFILE utilities described
below are better tuned for manipulating data in UFILE format.  CUPLOT
has online help.


Ufiles needed for a TRANSP run
------------------------------

A complete list of possible TRANSP input files can be obtained by typing:

$transphelp operations namelist trdat_namelist ufile_names

In practice, only a few 2d ufiles (TER, NER, and BOL) and 1d ufiles
(CUR, VSF, RBZ, NTX, L2B, BDI, VSB, POS, and RMN) are actually used for
a single TRANSP run.  All the ufiles to be read by TRANSP are listed in
the TRANSP input namelist.

UFILE manipulation utilities
----------------------------

UGRAF1 &2: 1d and 2d plotting
GSMOO1 &2: '' '' ''  smoothing 
GAVER1 &2: '' '' ''  averaging
EXTRAC   : Extract 1d slices or 2d blocks from 2d Ufiles
CONCAT   : Combine 1d Ufiles into a 2d Ufile
SPLICE & Splice2 : Splice together 1d and 2d Ufiles
PROPANE  : Hand create arbitrary UFiles data
ECPROG	 : Maps ECE data from frequency to R and does trimming of
	   of bad data from the edges.

Most of these are menu-driven, so you just have to explore the menu
options to figure out what they do. Other commands also defined by
"@usr:[ufiles]ufutil" (which is automatically done for most TFTR users
if they have the the line "@usr:[com]raxlog" in their command file) are:

ulook0, gaver0, gxint1, ufil2gfox, thin1, thin2, nulltron, and
thdat. 

Various TFTR archives-to-UFILE translators are defined by
"@usr:[com]trnslname", which is also called by "@usr:[com]raxlog".

All UFILES of TFTR data which you prepare for a TRANSP run should be
placed in your own directory, which you create with and point to with
the commands:
$CREATE/DIRECTORY TR_DISK:[yourname]
$DEFINE MY_UFILES TR_DISK:[yourname]

Preparing a TRANSP Namelist
---------------------------

Don't be discouraged by the large number of namelist inputs.  Most of
them have reasonable defaults.  A sample namelist which can be used as a
good starting template is

source:sampletr.dat

It contains lots of comments, and the main items which you need to
modify are marked with the character "!*".

trinf:[tftr.89]*tr.inf	!are the information files for old runs.

Submitting a TRANSP run
-----------------------

Most people can skip this section.  When you have a complete set of
Ufile data ready, tell Doug McCune, and he will run the actual TRANSP job.

But for those do-it-yourselfer's: First get a TRANSP run number 1234 to
use from Doug McCune.  Then do:

Login to TRANSP.  
$ Move TFTR	! to get to the active directory for TFTR TRANSP runs.
$ copy [yourdir]1234tr.dat *.*	!copy your namelist file over or
!$ activ 1233 1234	! use namelist and expert module from previous run.
$ prtran		!generate various command files needed for a new run.
$ trdat		!if desired to check the input data.
$ target hax	!to run your job on the cluster node HAX
$ submit 1234tr	!to start the batch job running.

! or
$enqueue 1234 ds03	! to queue to decstation #3.
$enqueue 1234 ds*	! to queue to the next available decstation.

$spawni trlook 1234 !converts transp ascii output to RPLOT binary format
! or, to copy the output from a decstation run to the vax, and run
! trlook on it in batch mode to enable RPLOT, do:
$trlook 1234 batch ds01	

$rplot 1234	    ! to let you look at the TRANSP results so far.
		    ! WARNING:  TRLOOK takes up to an hour!!!!!
$subfgrf 1234tr	    ! to post-process a TRANSP run which has gone has
		    ! far as you want it to go.

Debugging a TRANSP run
----------------------
*** dmc Feb 1984 ***
I have attempted to update the description here

To debug a particular routine (for example, TRTOFP, which is part of
library FPPMOD) that is part of TRANSP, do:

$dbxclear       ! clear the debug objects list
$dbxadd TRTOFP  ! put in the name TRTOFP
$dbxadd ...     ! put in other names if you like
$dbx            ! build debug libraries based on the names you supplied.
                ! debug libraries e.g. FPPMOD, containing debug compiled
                ! named routines, are created in the local directory.
                ! logical names e.g. FPPMOD are redefined to point to
                ! these debug libraries.
$del 1234db.exe;*	! to make sure any previous version is avoided.

$@1234TR DEBUG NOCHECK	! to link a debug version, or

$run 1234DB     ! to run debug version and read current restart records:
DBG>GO
1234		! tell it the run name
R		! tell it to restart from the last restart record.

$restore_logical	! once the fake FPPMOD is no longer needed.

To save the state of a TRANSP run at a particular time, make a copy of
1234rs.dat, 1234xf.pln, and 1234yf.pln.  For more information, type
"$transp operations vaxrun".  The CMS and MMS systems are used to manage
the TRANSP libraries.  See TRANSP$:[DOC]CMSMMS.MEM for more information.
For example, to add a new subroutine fppsub1 to library fppmod,
type:

$ setcms fppmod
$ cms create element fppsub1.for
$ cmsmms fppmod
$ uplib fppmod		!then update that library

To modify a common block variable in the middle of a TRANSP run
interactively:

Here's what you do:  Make a debug version of TRANSP.  Run it.  at
DBG> SET BREAK STEPON ... this causes the code to stop right after reading
the restart file, when the COMMON block is in a valid state for being
written back out.  When you get there, DBG> SET MODULE to something that
is debug compiled and has TRANSP COMMON in it.  Set your variable.  Then,
DBG> CALL WRSTRT to rewrite the restart file.  If MRSTRT.gt.1 you might
have to call WRSTRT more than once.

Be careful that you do not write the restart file from any place other
than the breakpoint on entry to STEPON -- chances are you will make an
unusable restart record.  STEPON itself does not have to be debug compiled, but
of course you must have something with TRCOM in it.


Online Documentation
--------------------

Note: several logical names and commands here are defined in
transp_setup.com described above.  Also, some of these files are fairly
large, but you can easily search for specific information by typing, for
example, "search source:transp.hlp recycling/w=10".

source:sampletr.dat !a sample namelist input file which includes
		    !a short description of most of the important
		    !namelist variables.

source:port.for	    !contains a 1+ line description of every variable
		    !in the TRANSP common block, including all of
		    !the TRANSP namelist inputs.  Longer descriptions
		    ! of variables and how they relate are in:

transphelp	    !A help file in VAX's tree menu format.
source:transp.hlp   !The text version of the above file.

source:plotgen.i    !contains 1-line description of possible plot variables
54320f03TF.PLN	    !contains 1-line description of plot variables
		    !actually used in run 54320f03.

source:*.*	    !contains all of the fortran source code for TRANSP,
		    ! which contain many comments on what is going on.

$help @usr transp   !brief intro to transp
$help @usr ufiles   !brief intro to ufiles and ufile utilities

transp$:[jet.pellet.data]transp_jet_intro.doc contains JET specific help
but which may be helpful even for a TFTR run as a checklist of the main
ufiles which need preparation.

Offline Documentation
---------------------

Doug McCune's 5 part "Seminar on how to prepare input for TRANSP", 1987.
Doug McCune, The UFILES Data File System, January 1982.

Other documents are available from Doug also.  And as Doug says, people
are one of the best sources of information.  Those at Princeton who are
fairly familiar with TRANSP are:

Doug McCune, Rob Goldston,  Bob McCann, Stan Kaye, Dick Wieland, Mike
Zarnstorff, Greg Hammett


Published References
--------------------

TRANSP is a major tokamak transport analysis code developed at the
Princeton Plasma Physics Laboratory.  A description of the basic physics
models in TRANSP can be found in: 

R.J. Hawruluk, "An Emperical Approach to Plasma Transport," Physics of
Plasmas CLose to Thermoncular Conditions, Vol. 1, Proc. of the Course
held in Varenna, 1979 (1980).

R.J. Goldston, et.al., "New techniques for calculating heat and paritcle
source rates due to neutral beam injection in axisymmetric tokamaks,"
Journal of Computational Physics, VOl. 43, (1981).

Examples of the recent use of TRANSP to analyze tokamak experiments can
be found in:

R.J. Goldston, et. al., "Edge and Central Heating Experiments," Plasma
Physics and Controlled Fusion, Proc. 14 Eur. Conf., Madrid (1987).

M.Z. Zarnstorff, et. al., "Bootstrap Current in TFTR," PRL Vol. 60 
(1988) 1306.

O. Gruber et.al., "MHD Stability and Transport of Beam Heated Asdex
Discharges in the Vicinity of the Beta Limin," Plasma Phys. and Contr.
Nucl. Fus. Res. 1986, 11th Conf. Proc., Kyoto, 1986.  IAEA, 1987.

M. Murakami, et.al., "?Initial NBI results from TFTR?"?, EPS conf.
Budapest (1985) or ANS meeting about the same time?