README

** About **
The magnetosphere package currently contains two modules: igrf and cxform.

Module igrf provides several useful methods based on IGRF v.11.
The wrapper has been written by David Parunakian, Skobeltsyn Institute of Nuclear Physics of the Moscow State University.
Feel free to contact me with improvement suggestions, questions etc at either rumith@srd.sinp.msu.ru or dp@xientific.info.
The model itself is the result of hard work of many people from different institutions, such as IAGA and NASA.
The source code and coefficient files used can be found at ftp://nssdcftp.gsfc.nasa.gov/models/geomagnetic/igrf/fortran_code/
More information on IGRF can be found here: http://www.ngdc.noaa.gov/IAGA/vmod/igrf.html

Module cxform provides access to one function - transform(), which can be used for transforming cartesian coordinates
from one coordinate system to another. Complete documentation on cxform, as well as the list of coordinate systems supported,
can be found at CXFORM official website http://nssdcftp.gsfc.nasa.gov/selected_software/coordinate_transform/


** Installation **
python setup.py install

IGRF coefficient files will be installed to /usr/local/lib/igrf.


** Usage **
To use igrf in your software after you have installed it, include the following line in your code:

import magnetosphere.igrf

After that, you can use the following functions:

igrf.dimo(year): 
	Find the geomagnetic dipole moment in Gauss (normalized to the Earth's radius) at the specified time (decimal year)

igrf.lb(lat, lon, alt, year):
	Find the L-shell and geomagnetic field intensity (l, b tuple) at the specified latitude, longitude, altitude and decimal year

igrf.b(lat, lon, alt, year):
	Find the Earth's magnetic field value (Bnorth, Beast, Bdown, Babs tuple) using the spherical harmonics model

igrf.b0(lat, lon, alt, year, stps):
	Find the smallest magnetic field strength on a field line. Stps is step size for field line tracing

Latitude and longitude should be specified in the geographic coordinate system.
Altitude should be specified in kilometers above sea level.
Decimal year is a float and looks like 2003.45.


Similarly, to use cxform, include the following line in your code:

import magnetosphere.cxform

The cxform module provides access to one function - transform(), which can be used for transforming cartesian coordinates
from one coordinate system to another. Complete documentation on cxform, as well as the list of coordinate systems supported,
can be found at CXFORM official website http://nssdcftp.gsfc.nasa.gov/selected_software/coordinate_transform/


** Legal **
This project is distributed under the terms of the GNU General Public License v.3. The full text of the license is available
in the LICENSE file.


CXFORM:  An IDL/C library to convert between spacecraft coordinate systems

Originally written by Ed Santiago (LANL), esm@pobox.com
Modified & maintained by Ryan Boller (NASA/GSFC), Ryan.A.Boller@nasa.gov

	
============================
  OVERVIEW
============================

The CXFORM package contains a set of routines to convert spacecraft coordinates
from one system to another, i.e., GSE-->GSM.  It is written in C and can be
used as either a C library (.so or .dll) or an IDL function (via DLM -- 
Dynamically Loadable Module -- interface).

It has been tested under SunOS v5.7, Microsoft Windows 2000/XP, Mac OS X 10.3 &
10.4, and Linux 2.4.20-28.9.  It has previously been tested under Solaris 2.6 and
DEC OSF/1 V4.0.

It is largely based on Mike Hapgood's excellent introduction to coordinate 
transformations, along with Markus Fraenz' "Heliospheric Coordinate Systems" 
and Christopher Russell's "Geophysical Coordinate Transformations":

	http://sspg1.bnsc.rl.ac.uk/Share/Coordinates/ct_home.htm
	http://www.space-plasma.qmul.ac.uk/heliocoords/
	http://www-ssc.igpp.ucla.edu/personnel/russell/papers/gct1.html/

Note that since this follows much of Hapgood's formulae that are optimized for
simplicity and efficiency, he specifies a level of precision of 0.001 degrees
up to the year 2100 for each rotation angle, which has been deemed sufficient
for space physics applications. The disclaimer applies that these should not
be used for mission-critical flight applications due to their margin of error.

Formal testing has been completed as of 2004/12/01.  The results can be found
on the CXFORM web page.  In general, they are within 1% of the results of
SSCWeb's calculations (based on GEOPACK), and in many cases are within
0.01%.

Questions/comments/suggestions are welcome to Ryan.A.Boller@nasa.gov


============================
  INSTALLATION
============================

See install.txt for instructions.


============================
  USAGE FROM IDL
============================

The function prototype is

	new = CXFORM( pos, source_frame, dest_frame, time )

where:
	pos		is a vector of length 3, containing the position
			in source_frame coordinates. It can also be a 2-D
			array of size [3, M], where M is the number of points
			to convert

	source_frame	is an ASCII string naming the source
			coordinate system, e.g., 'GSE', 'J2000'.  See 
			"Coordinate Systems Implemented" below.

	dest_frame	is also an ASCII string, naming the destination
			coordinate system.

	time		is "ephemeris seconds past J2000 (1 Jan 2000 12:00)".
			The "date2es" function converts a standard Gregorian
			time (mm,dd,yyyy) to Ephemeris Seconds past/before
			J2000.  See the included "date2es.pro" file for more 
			details.

	new		is the position, in dest_frame coordinates.



Single-coordinate example:

	IDL> es = date2es(9,30,1999,7,5,0)  ; Sep. 30, 1999 07:05:00 UTC
	IDL> pos = cxform([1,0,0], 'GSE', 'GEO', et)
	IDL> help,pos
	POS             DOUBLE    = Array[3]
	IDL> print,pos
	       0.32034915      0.94616669    -0.046314350
	IDL> 


Multiple-coordinate example:

	IDL> imp8GEI = fltarr(3, 5)
	IDL> imp8Time = lonarr(5)
	IDL>
	IDL> help, imp8GEI
	IMP8GEI		FLOAT		= Array[3, 5]
	IDL> help, imp8Time
	IMP8TIME	LONG		= Array[5]
	IDL>
	IDL>
	IDL> imp8GEI[*,0] = [-32.562, 20.085, -10.471]
	IDL> imp8GEI[*,1] = [-34.415, 4.229, -6.173]
	...
	IDL> print, imp8GEI
		-32.5620	20.0850		-10.4710
		-34.4150	4.22900		-6.17300
		-27.2210	-12.441		-0.34300
		-9.01000	-23.380		 5.39300
		 14.1890	-19.583		 7.58900
	IDL>
	IDL> imp8Time = [-43200, 43200, 129600, 216000, 302400]
	IDL>
	IDL> imp8GEO = cxform(imp8GEI, 'GEI', 'GEO', imp8Time)
	IDL>
	IDL> print, imp8GEO
       25.418317       28.593709      -10.471000
       10.691414       32.984396      -6.1729999
      -6.5404276       29.205893     -0.34299999
      -20.772292       14.011294       5.3930001
      -22.419840      -9.0648980       7.5890002


Note that if your data is imported as [M, 3] instead of [3, M], you can
transpose it using IDL's TRANSPOSE function:

	IDL> correctArr = fltarr(3, M)
	IDL> correctArr = TRANSPOSE(originalArr)

		
============================
  USAGE FROM C
============================

See main.c included in this package for an example of using CXFORM in C.
See install.txt for instructions on building it on your platform.


============================
  TEST RESULTS
============================

The bulk of the testing used SSCWeb's Locator Tabulator as the data source.
As stated in the introduction, this service uses GEOPACK for its calculations.
An included file, tester.c, was used to read in data from SSCWeb and
compare it to the results of CXFORM.  In addition, one data point was used from
the HelioCoords transformation package documentation as a sanity check and also
as a test for the heliospheric systems that are not present in SSCWeb.

See the following URL for links to the actual results:
http://nssdcftp.gsfc.nasa.gov/selected_software/coordinate_transform/#Test_Results

	
==================================
  COORDINATE SYSTEMS IMPLEMENTED
==================================

GEI			Geocentric Equatorial Inertial, also known as True
			Equator and True Equinox of Date, True of Date (TOD),
			ECI, or GCI
J2000			Geocentric Equatorial Inertial for epoch J2000.0 
			(GEI2000), also known as Mean Equator and Mean Equinox
			of J2000.0
GEO			Geographic, also known as Greenwich Rotating
			Coordinates (GRC), or Earth-fixed Greenwich (EFG)
MAG			Geomagnetic
GSE			Geocentric Solar Ecliptic
GSM			Geocentric Solar Magnetospheric
SM			Solar Magnetic
RTN*		Radial Tangential Normal (Earth-centered)
GSEQ		Geocentric Solar Equatorial
HEE			Heliocentric Earth Ecliptic
HAE			Heliocentric Aries Ecliptic
HEEQ		Heliocentric Earth Equatorial


* = this system has not been tested and should be treated as such


=================================
  ADDING NEW COORDINATE SYSTEMS
=================================

This package has been designed to allow for easy additions of new coordinate
systems.

All you need to do is define one transformation between the new system and any
of the existing ones.  Once you do that, the Perl script will generate code to
convert to all others.  This, of course, means that a working copy of Perl must
be installed.  You will need the IxHash module if it is not already installed.
It can be found at http://search.cpan.org/dist/Tie-IxHash/

Here's what you do:

  1. Edit the file cxform-manual.c and add a new function, xxxx_twixt_yyyy, 
     where `xxxx' is any existing coordinate frame, and `yyyy' is the new one.

  2. Run "perl gen_cxform_auto.pl cxform-manual.c" from the prompt. This will
     create a new cxform-auto.c with support for your new coordinate system.
     
  3. Build and install a new CXFORM library as described in install.txt.

  4. Run and test it in IDL/C.  That's it! 

If it works, please send me your code.  I will include it in the next 
distribution (with appropriate credit to you, of course).


============================
  VERSION HISTORY
============================

2000/06/21  v0.2  Ed Santiago:  Last released version from Ed.
2003/09/12  v0.3  Ryan Boller:  First modified version from Ryan.  Added RTN
		  and GSEQ systems, IGRF2000 model, slightly different time
		  manipulation, Windows support, additional documentation, and
		  standalone C functionality.
2004/03/19  v0.4  Ryan Boller:  Updated Makefile to auto-detect platform and
          to build under Mac OS X.  HEEQ system now implemented by Kristi
          Keller.
2004/05/21  v0.5  Ryan Boller:  Fixed small discrepancy in calculation of
          T0 and lambda0.  Results now match those of SSCWeb's (GEOPACK-
          based) when the mag pole lat/lon is fixed to their values,
          as they haven't updated their IGRF coefficients.
2004/12/01  v0.6  Ryan Boller: Finished comprehensive testing, posted results.
          Updated IGRF to Revision 9.  Moved cxRound, date2es, and
          gregorian_calendar_to_jd to cxform-manual.c so it is included
          in the shared library.
2006/10/19  v0.7  Ryan Boller: Updated IGRF coefficients to 10th generation.
          Fixed IDL DLM interface under Windows XP & IDL 6.0+. Updated
          installation documentation.
2009/11/25  v0.71  Ryan Boller: Updated Mac compiler flags to compile 32- and 
          64-bit versions on Intel- and PPC-based CPUs.  Fixed memory pointer
          problem on 64-bit machines (now using IDL_MEMINT instead of IDL_LONG
          in cxform-dlm.c).

============================
  KNOWN ISSUES / TODOs
============================

- Mac shared object does not link with C objects.  May need to convert to a
  dylib.  The shared object does work with the IDL DLM interface, though.
- RTN system needs to be tested for accuracy


IGRF -- Version 11 ----- March 14, 2010 (updated April 30, 2010)

The International Geomagnetic Reference Field (IGRF) model is the empirical 
representation of the Earth's magnetic field recommended for scientific use 
by a special Working Group of the International Association of Geomagnetism 
and Aeronomy (IAGA). The IGRF model represents the main (core) field without 
external sources. The model employs the usual spherical harmonics expansion 
of the scalar potential in geocentric coordinates. The IGRF model coefficients 
are based on all available data sources including geomagnetic measurements 
from observatories, ships, aircrafts and satellites.

The IGRF model consists of sets of coefficients for a global representation 
of the Earth magnetic field for the years 1945, 1950, 1955, etc. There are 
definitive coefficient sets (DGRF####.DAT; #### = year) for which no further 
revisions are anticipated and IGRF####.DAT and IGRF####S.DAT for which future 
updates are expected. IGRF####S.DAT provides the first time derivatives of 
the coefficients for extrapolation into the future. The 11th generation of the 
IGRF model (IGRF-11) consists of definitive coefficients sets for 1900 thru 
2005 (DGRF1945 thru DGRF2005) and prelimenary sets for 1900 to 1940 and for 
2010 (IGRF2010) and for extrapolating from 2005 to 2010 (IGRF2010s.DAT).

In combination with the IGRF coefficient sets different subroutines have been 
used to determine the components of the magnetic field vector and the L-value 
at a given location. This sofware package uses the subroutines FELDG (magnetic 
field vector) and SHELLG (L shell) developed by G. Kluge at the European Space 
Operations Center (ESOC). His use of inverse cartesian co- ordinates simplifies 
the computation. The IGRF subroutines were developed by A. Zunde of the U.S. 
Geological Survey (USGS). FELDG and SHELLG are included togehter with other 
funbctions and subroutines in the file SHELLIG.FOR. The program BILCAL.FOR 
produces tables of the geomagnetic field strength, vector components (B-abs., 
B-north, B-east, B-down, declination, inclination), equatorial/minimum field 
strength (B0), dipole moment, and L-value in latitude, longitude (geodetic), 
altitude, or year (decimal). In addition to the main driver program BILCAL.FOR
this distribution also includes a subroutine for computation of IGRF parameters
in the file IGRF_SUB.FOR. 

The IGRF homepage is at http://www.ngdc.noaa.gov/IAGA/vmod/igrf.html.