To:  TRANSP USERS

  *** The New Version TRDAT Program Has Been Installed into the
  *** TRANSP code system!

  *** User namelists will have to be converted!
  *** Changes to Ufile data may also be required!

      ... D. McCune, 26 March 1992


TRDAT is the data acquisition "front end" program for TRANSP.  It
reads and checks all physics data input (Ufiles) for TRANSP and
preprocesses the data for use by TRANSP itself.

TRDAT has been rewritten for three reasons:

  o  to use a code generator, to make it much easier to add new
     input data channels to TRDAT and TRANSP

  o  to redesign the program memory management and reduce the size
     (in memory) of the TRDAT program.

  o  to add user conveniences:  automatic units conversion and
     axis swap options.

The rewrite is now complete and the new TRDAT has been installed.
Details are documented in TRANSPHELP.

  ******* User Namelist Conversion *******

THE NEW TRDAT AFFECTS USER NAMELISTS AND SOME UFILE DATA.  It was not
practical to keep 100% compatibility with the old data while adapting
the system to have the regularity consistent with a code generator.  This
means that all user namelists must be converted before they can be used
as input to TRANSP, TRDAT, or PRTRAN.  A conversion program is provided.
This program will delete obsolete switches from your namelist and 
convert other switches to their modernized form.  Most namelists can
be converted succesfully using the conversion program; conversion of
very old namelists is not guaranteed to be successful, and may require
some hand editting.

To convert a namelist for a TRANSP run, do the following on the VAX:

  1.  set your default directory to the directory containing the
      namelist file.

  2.  give the command

         $ FIXNL

      and if prompted give the name of the tokamak to which your
      namelist pertains.  (If you are logged in as TRANSP and your
      namelist is in the tokamak work directory, FIXNL will figure
      out the tokamak by itself).

  3.  for each namelist you want to convert, give the runid.

FIXNL will scan through your namelist and determine whether it can
do a conversion.  If so, it will do it; giving indication of the changes
made.

The following namelist switches are affected:

TRANSP namelist:  NL2SID,NL2RCK,NL2NTW,NLSHNT,NLSHNE,NLSHTE,NLVERT
TRDAT namelist:  NLBOLO,NLDBUG,NNEDGE and friends, NTEDGE and friends,
  NVEDGE and friends, RTEDL1,RTEDL2,RNEDL1,RNEDL2,NSELRE, and KLUGED.

Most of these have not been in use or only have historical meaning.
However, some of these were used to control functionality that no
longer exists in the system-- e.g. the use of TRDAT to patch profile
data in the edge regions, which is no longer supported, and must now
be performed at the Ufile level.  (In designing the new TRDAT, a 
study of user namelists was made, and it was determined that the
edge patching feature of TRDAT was not being used by current day 
users.  It was decided at the new TRDAT design review in June 1991 to
discard the feature, since to maintain it would have required a major
effort).

For further information see the comments at the top of the source file
  TRANSP$:[CMSREF.FIXNL]FIXNL.FOR.

If FIXNL cannot fix your old namelist, it may mean that you have to
fix both your namelist and your Ufile data.  If you need help with 
this, you may contact D. McCune (send VMS mail to TRANSP).


   ******* User Ufile Conversion *******

In many cases, no Ufile conversion will be required.  On the other hand,
in many TFTR cases, a commonly used "RCY" Ufile will have to be modified
to fix a corrupt units label -- FIXNL detects this and writes a fast
conversion procedure for this Ufile.

The new TRDAT has a completely different error analysis algorithm than
the old TRDAT.  This means that data that was tolerated by the old TRDAT
is not guaranteed to be accepted by the new TRDAT.

Generally, the new TRDAT is stricter, but its strictness is under
namelist control.  Thus if the new TRDAT complains of a UFILE error,
the user usually has the option of either fixing the Ufile or relaxing
the error criterion with the namelist.

There are two major areas of change in error checking:  Ufiles units
labels, and time and space coverage analysis.

Units Labels
============

The new TRDAT is sensitive to Ufiles units labels; the old TRDAT ignored
these labels completely.  The reason for this new sensitivity is the
much repeated user request for automatic conversion of data units, e.g.
temperatures from KeV in the Ufile to eV desired by TRANSP, and for
automatic swapping of axes of 2d Ufiles to the TRANSP convention of
time contiguous storage.  Automation of these features requires TRDAT
knowing the units of the data and independent coordinates of the Ufiles;
therefore, TRDAT must be sensitive to units labels.

Unfortunately, since the old TRDAT ignored units labels, the possibility
exists that many Ufiles successfully used in old TRANSP runs will not
be accepted by the new TRANSP because of corrupt units labels that the
old code ignored (unless LFIXUP=0 is set explicitly in the namelist).

The global namelist control LFIXUP is used to control units label 
checking behaviour.  The default value is LFIXUP=1.  FIXNL does not
write a value of LFIXUP into the namelist, so, generally, the default
value will apply, initially.

The following values of LFIXUP are supported:

  LFIXUP=0:  compatibility mode:  ignore the units in the input Ufiles.
    Invalid units errors will produce a warning message only.

  LFIXUP=1:  default mode:  require the units in the input Ufiles to
    be correct.  In batch, TRDAT will abort a TRANSP job if units errors
    are detected, or if 2d Ufile independent coordinates out of order
    are detected.

  LFIXUP=2:  fixup mode:  attempt to convert input Ufiles data according
    to the units labels found.  For example, if a temperature Ufile has
    a units label of "KeV", multiply the data by 1000.0 to make it "eV"
    as expected by TRANSP.  Also, swap axes of 2d Ufiles if the time
    coordinate is in the wrong place.

RECOMMENDATIONS:  for old cases, do what is convenient (i.e. LFIXUP=0 if
necessary).  For new runs, make sure that the Ufiles you create have
proper units labels.  When this has been assured, you may want to switch
to LFIXUP=2 to gain automatic units conversion.  This will often save
some steps in the Ufile preparation process for new data.


Range Checking
==============

Under the old TRDAT, input Ufile data was assumed to give appropriate
time and space coverage without checking.  This assumption was often
false, leading to many bizarre and cpu- and human- time wasteful TRANSP
analyses.

The new TRDAT actually checks the time and space coverage of input 
Ufiles relative to the time range (TINIT,FTIME) of the analysis set in
the namelist, and the spatial range implied by input plasma position or
plasma boundary data.

Input Ufiles are not required to cover the entire time range of the
analysis, but the INTERSECTION of their time range with the analysis
time range must not be the null set!  If any input Ufile timebase 
has no time points in range, that data will not be accepted (and 
the run cannot proceed).

Spatial coverage for profile input Ufiles now defaults to a rather
stringent standard.  For example, "two sided data" must by default
cover the range x=-0.9 to x=0.9 **AT ALL TIMES** (x = normalized
midplane coordinate = (R-R0)/a), or an error is reported.  For 
more details on spatial coverage, see TRANSPHELP.

Spatial coverage requirements can be waived, either on a Ufile by
Ufile basis (the namelist control XRCxxx for input profile type xxx),
or for ALL input Ufiles using the TRDAT namelist control RMJCHK.

For details, see TRANSPHELP.

RECOMMENDATION:  For reruns of old cases, do what is convenient.
Consider fixing your old Ufiles, if necessary.  You may discover some
errors in your old analyses.  When preparing new data, you should
try to meet the default TRDAT coverage requirements.  To benefit from
the TRDAT range checking, do not leave the disabling RMJCHK=-1.0 in
your namelist templates.

If you have questions or problems with using the new TRDAT and TRANSP,
contact Doug McCune -- send VMS mail to TRANSP.