(back)
//
//##########################################################################
// T89c.c #
// A C-language version of the Tsyganenko T89c model of #
// Earth's magnetospheric magnetic field. #
//##########################################################################
//
//
// A Brief Description (from Dr. Tsyganenko's magnetic field software page
// "Tsyganenko Magnetic Field Model and GEOPACK s/w" at
// http://nssdc.gsfc.nasa.gov/space/model/magnetos/tsygan.html):
// "
// Availability:
// The latest versions (1989c, 1996 and 2001) of the models and
// related software can be retrieved from the homepage:
// http://nssdc.gsfc.nasa.gov/space/model/magnetos/data-based/modeling.html
//
// Brief Description:
//
// The Tsyganenko model is a semi-empirical best-fit representation for
// the magnetic field, based on a large number of satellite observations
// (IMP, HEOS, ISEE, Polar, Geotail, etc). The model includes the
// contributions from external magnetospheric sources: ring current,
// magnetotail current system, magnetopause currents and large-scale
// system of field-aligned currents. The model author also provides
// GEOPACK
// which calculate contribution from internal sources and
// programs coordinate transformations.
//
// Additionaly NSSDC has a separate module which calculates contribution
// from Earth's internal field sources(e.g.:International Geomagnetic
// Reference Field (IGRF) model) for computing the B and other related
// parameters, and tracing the field lines.
// "
//
//
//
// The original model code appears in Fortran at the NSSDC URL below.
//
// This is a C-language (with C99 extensions) "alpha" (i.e., v0.0.2)
// version of Dr. Tsyganenko's T89c model of Earth's magnetospheric
// magnetic field.
//
// The author and originator of the model is:
// Dr. N. A. Tsyganenko, email: kolya@nssdca.gsfc.nasa.gov
// (301) 286-7925 FAX: (301) 286-1681
// Code 690.2, NASA/GSFC Greenbelt, Maryland 20771
//
// Please direct questions about the science and model construction to him.
// Dr. Tsyganenko is aware of this effort, but is not responsible for its
// accuracy, operation, or maintenance.
//
//
// View/Download the C-version (text/zip).
//
// This C-version (text/zip) was ported from the Fortran version (see
// URL below) in order to extend the usefulness of the model into areas
// of scientific magnetospheric research in which C is more often used
// by: Stephen Christon email: Steve.Christon@gsfc.nasa.gov
// or gotofar@mac.com
//
// Please direct questions about the Fortran-to-C conversion to me.
//
// DISCLAIMER:: Use this C-code at your own risk. Although I ported it and
// tested it to some extent, the user alone is responsible for
// any consequences resulting from its use.
//
// Notes on the C-port (text/zip) by Steve Christon (12.Dec.2003):
// ------------------------------------------------------------------------
//
// I have retained most of the comments included by Dr. Tsyganenko.
// However, some comments have been slightly changed. If in doubt,
// consult the original code which can be found at:
//
// http://nssdc.gsfc.nasa.gov/space/model/magnetos/data-based/modeling.html
//
// (see also http://nssdc.gsfc.nasa.gov/space/model/magnetos/tsygan.html).
//
// This first version of the T89c C-port is simple and direct, as one
// can see by comparing the two versions. A number of whitepapers
// discuss C-Fortran compiled-code speed comparisons and they generally
// conclude that Fortran is typically faster. My initial speed tests
// are consistent with this. However, the C-version is not highly-
// optimized yet, and I anticipate that individuals in the scientific
// community may be able to help improve this code for the community's
// shared benefit. I have attempted to make the C-code as efficient
// as possible, but I am convinced that suggestions from others
// should help to improve the C-version's efficiency and speed.
// Most Fortran common block variables are incorporated into global
// data structures shared if needed by the application's subroutines.
// The T89c and Geopack global variables are in separate structures.
// Parameter passing to subroutines is done as "call-by-reference".
//
// T89c is not the newest or most accurate of Dr. Tsyganenko's
// magnetospheric models, but it is a fast version that includes a
// tilted dipole and much recent data (see Dr. Tsyganenko's notes).
// Therefore, it is useful for a wide variety of studies and as a
// teaching aid.
//
// My motivation for the port is twofold:
//
// (a) Today, scientific computer studies often use CC++ rather
// than Fortran because Fortran is less frquently taught in
// Computer Science courses. C is more widely documented.
//
// (b) Commercial Fortran compilers are typically expensive.
//
// The T89c C-code compiles and runs in the free GNU GCC C-compiler
// which can be found at:
//
// http://www.gnu.org/software/gcc/gcc.html
//
// ( Various GNU materials are Copyright (C) by the
// Free Software Foundation, Inc.,
// 59 Temple Place - Suite 330,
// Boston, MA 02111, USA. )
//
// This C-version of T89c, Geopack, and the two examples were converted
// from the Fortran-versions available at NSSDC and tested primarily on
// Mac OSX (and less frequently on Sun Solaris) operating systems in the
// process of conducting research at NASA/GSFC funded by the NAS/NRC.
//
// I am making this T98c C-code available for shared use and improvement
// by the worldwide scientific community.
//
// The Fortran version of T89c compiles in the GNU Fortran G77 compiler,
// but more interest and maintenance activity is focused on GCC than G77.
//
//
// This package includes three separate files, called:
// trt98c.c ... the example program that uses T89c to:
// ...... (a) evaluate T89c at various chosen points
// ...... (b) produce a magnetic field map
// ...... (c) trace field lines (Tsyganenko's example 1)
// t89c.h ... a shared header file
// t89c.c ... the T89c model and associated Geopack routines
//
// The files are compiled and run in GCC using the following
// command-line instructions (which provide some optimization):
//
// (on Mac OSX 10.2+ this command line worked for me)
// >> gcc -O2 -ffast-math -o trt89c trt89c.c t89c.c
// >> ./trt89c
//
// (on a RHLinux/Pentium machine and a Sun/Solaris machine this command
// line worked for me)
// >> gcc -lm -O2 -ffast-math -o trt89c trt89c.c t89c.c
// >> ./trt89c
//
// What does trt89c do?
// --------------------
//
// When you start the program (./trt89c), it prints these two lines:
//
// >> start trt89c::
// >> enter: -1/0/1/2 for t89-only/bmap/Ex.1/Ex.2 [1i]::
//
// trt89c gives you three choices, -1, 0, or 1:
//
// -1 :: here we calculate only magnetic field contributions
// from the major magnetospheric current systems. These
// then need to be added to the intrinsic model magnetic
// field to estimate the measured field at any location.
// trt89c asks you to enter numbers for the geomagnetic
// activity level, dipole tilt angle, and xyz location
// in the GSM Earth centered cartesian coordinate system:
//
// >> enter: level(1-7,0=exit),tilt[rd],x,y,z[Re] [i,4f]::
//
// If you enter ** 1 0.25 -11. 1. 0. ** for example,
// trt89c should return the following values for Btot,
// BX, BY, and BZ:
//
// >> 2.0201911e+01 -1.5973811e+01 1.0456650e+00 -1.2323196e+01
//
// which is the same answer the Fortran version returns
// - to at least 5 significant figures on the various
// computer operating systems (MacOSX, Solaris, and Linux)
// that I have run them on to date.
//
// In order to make t98c.for, the Fortran version, run
// correctly in g77 (also from www.gnu.org), I declared
// all variables (as either real*8 or integer*4 and used
// implicit none).
//
// For direct point-to-point comparison, I modified the
// small example program provided by Dr. Tsyganenko at
// the head of t89c.for as shown here:
//
// program runt89c ! fortran sample program
// implicit none
// real*8 parmod(10),ps,x,y,z,bx,by,bz,bt
// integer*4 iopt
// 1 print *, ' enter x,y,z,ps,iopt'
// read*, x,y,z,ps,iopt
// call t89c(iopt,parmod,ps,x,y,z,bx,by,bz)
// bt = dsqrt(bx*bx+by*by+bz*bz)
// print *, bt,bx,by,bz
// goto 1
// end
//
//
// 0 :: trt89c calculates a map of Btot, BX, BY, or BZ for the
// total (T89c and intrinsic) magnetic field. A dipole
// model is used in the calculations. Btot is calculated
// over a grid every 2 Re: in X from -31 to 1 Re, Y from
// -21 to 21 Re, and Z from -10 to 10 Re. The date and
// geomagnetic activity level are input parameters. This
// allows one to generate a large number of field values
// for comparison with output from the fortran version
// of from different computers.
//
// 1 :: (seems to be working) trt89c runs Example 1
// from Geopack (the 2001 version). I think this is now
// working correctly, but I do not have extra time right
// now to verify its operation thoroughly.
//
// 2 :: (seems to be working) trt89c runs Example 2
// from Geopack (the 2001 version). I think this is now
// working correctly, but I do not have extra time right
// now to verify its operation thoroughly.
//
// What works and what does not work?
// ----------------------------------
//
// o T98c C-code field model values compare well with values from the
// Fortran version. If you find any inconsistencies, email the error
// output to me.
//
// o I think that my current version of the Geopack trace() routine
// now works correctly. But, I have only put it through some very
// minimal tests. I will put it through more rigorous tests at some
// point, but the operation of the trace subroutine does not affect
// the operation of the T89c C-code field model (which has been tested
// and checked extensively) in any way.
//
// Finally, the following routines were converted and compile but have
// not been verified yet: geomag, geigeo, magsm, gsmgse, smgsm, locate.
//
// DISCLAIMER:: Use this C-code at your own risk. Although I ported it and
// tested it to some extent, the user alone is responsible for
// any consequences resulting from its use.
//
//
// Steve Christon 12.Dec.2003 last updated: 28.Jan.2004
//
//--------------------------------------------------------------------------