=========================================================================
National Space Science Data Center      Data set  MG-25B      23 Jan 1991 
=========================================================================

NAME		Tsyganenko 1987 Model and Related Software

SCIENTIFIC CONTACT	N.A. Tsyganenko, NASA, GSFC, Code 696
			on leave from Institute of Physics, 
			Leningrad State University, Stary Peterof 198904, 
			Leningrad, U.S.S.R.

NSSDC CONTACT		S. Kayser, NASA/GSFC/NSSDC, code 633.9/HSTX, 
                        Greenbelt, Maryland 20771, U.S.A., NCF::KAYSER

CONTENT: 16 files

  name         blocks          description
--------------------------------------------------------------------------
CHANGES.LOG	 5	Documents modifications to code
CURL87.FOR       9      SR to calculate curl B at a point, using T87
DR_T87.FOR	20	Driver for T87
IGRF80.DAT       6  	The IGRF 1980 model parameters (alternate to MAG80)
INT87.DAT	 4	Sample input to DR_T87
KP.DAT           2	Holds some Kp values for T87 pgm (for CDAW 8,9)
MAGLINE.FOR	60	Calculates field lines through points, using T87
MAGLINE.OUTPUT	59	Concatenated output from MAGLINE for STARTLINE
MAG80.DAT       11 	Holds Magsat 80 constants for Main B, for T87 pgm
PAR87.DAT        4	Holds "long model" T87 constants, for T87 pgm
PAR87A.DAT       4	Holds "short model" T87 constants, for T87 pgm
DOCUMENTATION.TXT 8	User's Guide to T87 
STARTLINE.DAT	 1	Sample input to MAGLINE
T87.FOR        146  	The T87 model, except for a driver
T87OUT.DAT	 6	Output from DR_T87 for INT87
AAAREADME.DOC   13	This file
----------------------------------------------------------------------------
	The 1989 version of the Tsyganenko model is available in the
	TSYGANENKO89 directory.

INSTRUCTION:    NSI-DECnet:     use COPY command
     COPY/LOG NSSDCA::ANON_DIR:[000000.MODELS.TSYGANENKO87]*.* *.*
                Internet:       use anonymous FTP
     FTP NSSDCA.GSFC.NASA.GOV, login, username=ANONYMOUS,
     password=your_network_address, CD MODELS, CD TSYGANENKO87, use DIR
     and GET commands and QUIT to exit.

BRIEF DESCRIPTION:

     This software package contains the FORTRAN code and data files needed to
run the Tsyganenko 1987 (T87) magnetospheric model on a VAX.  The code was
written by Dr. David Stern (LEPVAX::U2DPS) and modified by Dr. Susan Kayser
(NCF::KAYSER). To run on a PC or other machine, the OPEN/CLOSE statements in
the code should be removed or replaced by Fortran calls appropriate to the
user's system.  Some variables in the code have names with more than 6
characters; these may also have to be altered for the user's system. 
Read the prologues to DR_T87, MAGLINE, and T87.FOR.  These explain the
programs, and also the usage (including input files). 

To run the model, first compile, and link your driver and the T87 package, e.g.
     $ LINK DR_T87,CURL87,T87
or   $ LINK MAGLINE,T87

The input data files IGRF80, KP, MAG80, PAR87, and PAR87A are assumed to reside
in the logical directory MODEL$DAT.  Therefore, before running the model, you
must assign the actual directory to MODEL$DAT:   
     $ ASSIGN [directory] MODEL$DAT
This command may be put in your LOGIN.COM file.  The driver DR_T87 shows how to
do this dynamically.  To use IGRF80 instead of MAG80, you must rename IGRF80 to
MAG80. In MAGLINE, change USERDIR to the MODEL$DAT directory.

Various parameters have defaults provided.  To change these, modify the coding 
in the drivers as desired.  For example, to find curl B at each point, set 
ICURL = 1 in DR_T87.  The amount of output may be modified via IOUT, QSAVE (in
MAGLINE).  You could also add a line at the beginning of your input file
containing values of these parameters, to allow you to alter them frequently 
with ease.

To get individual points, modify the INT87.DAT file to include the points for
which you want the field.  Then,
     $ RUN DR_T87
To trace field lines, modify STARTLINE.DAT to include the points through which 
you want field lines.  Then $ RUN MAGLINE .

The present version of MAGLINE calculates up to 50 lines (with up to 200 
points) for a given date or tilt angle, using T87.  It contains a plot program
stub, which accepts the calculations, but doesn't do anything with them yet. 
Future versions of MAGLINE may allow other models to be called, e.g. the Stern
Stretch model and the Tsyganenko 1989 model, and may have a complete plot
program.  Watch this space! 

Please check the CHANGES.LOG file from time to time, to learn if any programs 
have been updated.  Suggestions and corrections may be sent to Susan Kayser.

The 1987 Tsyganenko model is based on IMP-A,B,C,D,E,F,G,H,I,J and HEOS-1,2
measurements over the time period 1966 to 1980, using a total of 36682 data
points. It describes the magnetic field from about 4 to 70 Re (Earth radii) for
several levels of magnetic disturbance. Two versions were established, a 'long'
version with 26 parameters and 6 disturbance levels, valid up to 70 Re, and a
'short' version with 20 parameters and 8 disturbance levels, valid up to 30 Re.

The package is available online and can be also obtained on tape, or on 
diskette.


REFERENCES                               

N.W. Peddie, A third generation of International Geomagnetic Reference Field
models, J. Geomag. Geoelectr. 34, 310-320, 1982 

N.A. Tsyganenko, A.V. Usmanov, Determination of the magnetospheric current
system parameters and development of experimental geomagnetic field models
based on data from IMP and HEOS satellites, Planet. Space Sci. 30, 985-998,
1982 

N.A. Tsyganenko, A.V. Usmanov, V.O. Papitashvili, N.E. Papitashvili, V.A.
Popov, Software for computations of the geomagnetic field and related
coordinate systems, Soviet Geophysical Committee, Special Report, 58p, Moscow,
1987 
                           
N.A. Tsyganenko, Global quantitative models of the geomagnetic field in the
cislunar magnetosphere for different disturbance levels, Planet. Space Sci. 35,
1347-1358, 1987 

N.A. Tsyganenko, A magnetospheric magnetic field model with a wrapped tail
current sheet, Planet. Space Sci. 37, 5-20, 1989 
(These changes are NOT included in this software package, but code for this
1989 model is available--see TSY89.TXT) 

=========================================================================
National Space Science Data Center      Data set  MG-25B      23 Jan 1991 
=========================================================================