DMC Feb 1992:  This file contains PPPL-specific documentation for using 
the MGTSUB system for doing time dependent mapping of Shafranov-shifted
circular magnetic flux surfaces, e.g. for diagnostic data analysis.  An
example of use of MGTSUB is in the TRANSP ECPROG program.

To install MGTSUB in your application, you will need to link the following
libraries:

TRANSP$:[OBJ.LIB]MGTSUB.OLB		! MGTSUB 
TRANSP$:[OBJ.LIB]TFTRG1.OLB		! interactive TFTR waveform read
TRANSP$:[OBJ.LIB]INTERP_SUB.OLB		! interpolation 
TRANSP$:[OBJ.LIB]RPLOT_SUB.OLB		! internal memory management
TRANSP$:[OBJ.LIB]SMLIB.OLB		! data smoothing routines
TRANSP$:[OBJ.LIB]UFLIB.OLB		! UFILES routines
TRANSP$:[OBJ.LIB]GFLIB.OLB		! interactive user interface
                                        ! (UREAD and graphics)
and:

USR:[LIB]CMLIB_NOSHR.OLB		! CMLIB TFTR data access routines
USR:[LIB]OP_RESULTS.OLB			! laser jukebox access routines
USR:[LIB]JUKELIB_SHR.OLB		! more laser access routines
USR:[PLOT]SGNEW.OLB			! SGLIB graphics


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

in your applications program, do the following:

(1)  at the start of the program,

      CALL UINITA(0)

to set up the UREAD user interface system.

UREAD is a command oriented user interface system with programmable
scripting capabilities.  For more information use the symbol URHELP
which should be defined as "HELP/LIBRARY=USR:[HELP]UREAD UREAD".

CAUTION -- UREAD uses FORTRAN logical units no.s 10--20 by default.

(2)  in the body of your program,
to set up the Shafranov map and field correction calculation for a 
particular shot,

      CALL MAGGEO(LUNWF,NSHOT,IER)

with input LUNWF = a FORTRAN logical unit number available for use in
TFTR waveform and/or Ufile i/o,
     input NSHOT = the integer shot number of the TFTR shot being examined.

     output IER=0 on exit if MAGGEO executed successfully and the user
       accepted the results; IER.NE.0 otherwise.

MAGGEO takes the user through an interactive menu driven interface to
read in the TFTR magnetics waveform data and evaluate the Shafranov
shift and field correction profiles as functions of time.  The interaction
is via UREAD, and may be scripted in the usual way.

(3)  after calling MAGGEO, to get the plasma minor and major radius and 
a profile of flux surface shifts at a given time, use the MAGSHF routine:

C-----------------------------------------------------------------
C  MAGSHF - RETURN R0, A, SHIFT PROFILE INTERPOLATED OUT OF MAGNETICS
C           COMMON BLOCK
C
	SUBROUTINE MAGSHF(ZTIME,ZR0,ZA,ZX,ZSHIF,INX,IER)
C
	REAL ZX(INX)	! FLUX SURFACE LABELS (R/A) INPUT **
	REAL ZSHIF(INX)	! FLUX SURFACE SHIFTS (CM) OUTPUT **
C                         SHIFT=0.0 AT R/A = 1.0
C
C	ZTIME		! TIME, SECONDS, TO INTERPOLATE AT, INPUT
C
C	ZR0		! MAJOR RADIUS OF OUTER SURFACE, CM, OUTPUT
C	ZA		! MINOR RADIUS OF OUTER SURFACE, CM, OUTPUT
C
C	IER		! COMPLETION CODE, OUTPUT
C	    =0 NORMAL, SUCCESSFUL COMPLETION
C	    =1 (FLAT) TIME EXTRAPOLATION OF MAGNETICS DATA
C	    =2 ERROR -- NO PRECEEDING MAGGEO CALL TO READ MAGNETICS
C		    DATA AND LOAD UP THE COMMON BLOCK
C

(4)  after calling MAGGEO, to get ALL magnetics data available from the
system, use the MAGDAT routine:

C-----------------------------------------------------------------
C  MAGDAT - RETURN ALL MAGGEO DATA, INTERPOLATED IN TIME & SPACE
C
	SUBROUTINE MAGDAT(ZTIME,ZX,INX,
     >    ZR0,ZA,ZCUR,ZRBT,ZLAM,ZBETA,
     >    ZPRES,ZQ,ZSHIF,ZG,ZF,
     >    IER)
C
C
C  INPUTS:
C
C	ZTIME		! TIME, SECONDS, TO INTERPOLATE AT, INPUT
C
	REAL ZX(INX)	! FLUX SURFACE LABELS (R/A) INPUT **
C
C       ... ARRAY OF (INX) VALUES IN ASCENDING ORDER BTW. 0 AND 1 
C
C  SCALAR OUTPUTS:  (INTERPOLATION OF MAGGEO INPUT DATA):
C
C	ZR0		! MAJOR RADIUS OF OUTER SURFACE, CM
C	ZA		! MINOR RADIUS OF OUTER SURFACE, CM
C       ZCUR            ! PLASMA CURRENT, AMPS
C       ZRBT            ! R*B(TOROIDAL), TESLA*CM
C       ZLAM            ! LAMDA (LI/2+BETA(POLOIDAL)), DIMENSIONLESS
C       ZBETA           ! BETA(POLOIDAL) (DIAMAGNETIC), DIMENSIONLESS
C
C  PROFILE OUTPUTS (FLUX SURFACE FUNCTIONS):
C
	REAL ZPRES(INX) ! MAGGEO EST. PLASMA PRESSURE PROFILE (JLES/CM3)
	REAL ZQ(INX)    ! MAGGEO EST. Q PROFILE (DIMENSIONLESS)
	REAL ZSHIF(INX)	! FLUX SURFACE SHIFTS (CM) 
C                         SHIFT=0.0 AT R/A = 1.0
	REAL ZG(INX)    ! TOROIDAL FIELD CORRECTION BT/BT(VACUUM)
	REAL ZF(INX)    ! TOTAL FIELD CORRECTION B/BT(VACUUM)
C
C          BT(VACUUM) = ZRBT / R   WHERE R = A MAJOR RADIUS LOCATION
C
C
C  STATUS OUTPUT:
C
C	IER		! COMPLETION CODE, OUTPUT
C	    =0 NORMAL, SUCCESSFUL COMPLETION
C	    =1 (FLAT) TIME EXTRAPOLATION OF MAGNETICS DATA
C	    =2 ERROR -- NO PRECEEDING MAGGEO CALL TO READ MAGNETICS
C		    DATA AND LOAD UP THE COMMON BLOCK
C

(5)  readonly copies of the sources for TRANSP subroutines are in the
directory SOURCE_MGTSUB.  For example, the source for subroutine MAGDAT 
of the library TRANSP$:[OBJ.LIB]MGTSUB.OLB is found in

  SOURCE_MGTSUB:MAGDAT.FOR.

(If SOURCE_MGTSUB is not defined for you, you are not set up as a TRANSP
user; see $ HELP TRANSP).

(6)  questions, comments, etc. to D. McCune (send VMS MAIL to
DMCCUNE or TRANSP)

DMC 8-Aug-1990
