FAST get_fa_orbit IDL routine - values returned

get_fa_orbit is an IDL routine provided by the UC Berkeley FAST team that provides spacecraft ephemeris and other orbit-related parameters.

get_fa_orbit returns orbit data as tplot variables (these are IDL data structures used by the time series plotting routines distributed in the FAST IDL library). This document describes the values returned by the routine, as well as the methods used to verify these return values. It does not describe how to call the routine in detail, although a typical call would be:
where t1 and t2 are the start and stop times,
the /all keyword means get all orbit parameters,
and delta=1. means output the orbit data at 1 second time steps.
The last two key words define how to propagate the orbit forward in time.

For more details on calling the routine see the discussion in the get_fa_orbit procedure included in the FAST IDL software distribution.

The values returned by get_fa_orbit can be blocked into the following subsets:

Spacecraft Ephemeris (fa_pos, fa_vel, ORBIT)

Spacecraft Position in Geographic Coordinates (LAT, LNG, ALT)

Spacecraft Position in Magnetic Coordinates (ILAT, ILNG, MLT)

Magnetic Model (B_model)

Magnetic Footprint (FLAT, FLNG, BFOOT)

Spacecraft Ephemeris


Spacecraft position in km, in Geocentric Equatorial Inertial (GEI) Coordinates. Verified as inertial coordinate system by change in azimuth, ~ -0.04 degrees, between beginning and end of orbit. (For a definition of GEI and other geophysical coordinates, see Geophysical Coordinate Transformations, C.T. Russell, originally published in: Cosmic Electrodynamics, 2, 184-196, 1971. All rights reserved. Copyright 1971 by D. Reidel, Publishing Company Dordrecht-Holland.)


Spacecraft velocity in km/s, in GEI. Verified equatorial by calculating orbit normal from vector cross product of fa_pos and fa_vel. Resultant orbit normal elevation found to be fixed at about 7 degrees, i.e. ~ 83 degrees inclination (launch inclination). An ecliptic-based coordinate system would have secular variation (solar obliquity).


Orbit number, changes at ascending node, when z_gei of spacecraft crosses zero from negative to positive.


Spacecraft Position in Geographic Coordinates


Geographic latitude of spacecraft in degrees, for spherical earth. Verified by independent algorithm to transform spacecraft position from GEI to GEO (geographic) coordinates. Latitude difference < 0.00001 degrees, which should be compared with ~ 0.2 degree difference between geocentric and geodetic (ellipsoidal earth) latitudes at 45 degrees geographic latitude).


Geographic longitude of spacecraft in degrees, for spherical earth. Verified by independent calculation of spacecraft position in GEO coordinates.


Altitude of the spacecraft in km, relative to equatorial radius. Verified by calculating radial distance (from fa_pos) - altitude, = 6378.14 for entire orbit (6378.14 = equatorial radius, 6371.2 = mean radius). NOT geodetic (ellipsoidal earth) altitude.


Spacecraft Position in Magnetic Coordinates

The parameters ILAT, ILNG, and MLT are related to the spacecraft position in offset-tilted dipole coordinates. This coordinate system is defined as follows, with respect to geographic coordinates:

origin: geographical position of the offset tilted dipole
z-axis: along dipole axis, positive to the north
y-axis: given by cross-product of earth spin axis (positive to the north) and dipole axis
x-axis: completes triad.

Note that the earth's spin axis lies in a plane parallel to the x-z plane of this coordinate system, and points to 180 degrees magnetic longitude.

Spacecraft position in geographic (spherical earth) coordinates is converted to magnetic coordinates by first translating to a system referenced to the geographic position of the offset tilted dipole, and then rotating to the coordinate system given above. This gives a modified radial distance (m_rad), as well as a magnetic latitude (m_lat) and magnetic longitude (m_lng).

For reference, the geographic coordinates of the offset tilted dipole used in get_fa_orbit are:

position: [-402.199, 287.504, 195.908] km
latitude: 79.3637 degrees
longitude: 288.454 degrees


Invariant latitude of the spacecraft in degrees, based on magnetic coordinate system defined above. Uses standard equation for invariant latitude in a dipole field, cos^2(ILAT) = (6371.2/m_rad)*cos^2(m_lat). Note that this definition of invariant latitude is derived from the L-shell given by the equatorial distance of the dipole field line passing through the spacecraft position, using the offset tilted dipole to define the origin and equator [cos^2(ILAT) = 1/L]. It is not the magnetic latitude of the 1 earth radius footprint, nor is it the same as the "Altitude Adjusted Corrected Geomagnetic Coordinates" invariant latitude, which is given by the geocentric equatorial distance of the IGRF field line passing through the spacecraft position. Verified by direct calculation for FAST orbit 1761, difference found to be less than 0.05 degrees.


Magnetic longitude of the spacecraft in degrees (same as m_lng). Verified by direct calculation for orbit 1761, difference found to be less than 0.5 degrees, with the largest deviation occuring near 90 degrees latitude.


Magnetic local time of the spacecraft, in hours. MLT is given by the difference between ILNG and the Sun's longitude in magnetic coordinates, converted to hours, with 12 hours corresponding to ILNG = Sun's longitude. Verified by direct calculation for orbit 1761, difference found to be less than 0.05 hours, with the largest deviation occuring near 90 degrees latitude.


Magnetic Model


Model magnetic field (nT) in Geocentric Equatorial Inertial coordinates. Specified by IGRF model for the epoch of the data passed to get_fa_orbit. The model includes coefficients to the 11th order, based on the MAGSAT IGRF coefficients given by the configuration file mag4wi.dat. Verified by direct comparison for orbit 1761, using an independently coded IGRF model calculation.

NOTE: Any FAST software installation may contain more than one version of mag4wi.dat. For example, while a version of mag4wi.dat that uses IGRF 1995 is included in the "delivery" software, get_fa_orbit uses a version of the file in $FASTCONFIG/Fastorb/mag4wi.dat [$FASTCONFIG is an environment variable defined when running the FAST code]. This directory is meant to be used for local configuration files that over-ride the defaults, but get_fa_orbit appears to require $FASTCONFIG/Fastorb/mag4wi.dat be present. Files in $FASTCONFIG are not updated via "delivery." When initially comparing models it was found that get_fa_orbit was using IGRF 1990. A substantial improvement in the comparison between get_fa_orbit and the independently coded IGRF model was found on replacing the $FASTCONFIG/Fastorb/mag4wi.dat file with the version in delivery. The reference epoch of the mag4wi.dat files installed can be checked by:
grep " 199" `find /disks/fast/software/ -name "mag4wi.dat" -print`
where /disks/fast/software should be replaced with the root directory for the site specific FAST software installation.

The current version of the IGRF model used by FAST is the 1995 revision (also referred to as the IGRF 7th generation model, see IAGA Division V-MOD Geomagnetic Field Modeling: Minutes Sapporo 2003). The file mag4wi.dat contains the coefficients for this version of the IGRF model. You can use this file to update the file in $FASTCONFIG/Fastorb/mag4wi.dat, but this version will over-ride any future update in "delivery."


Magnetic Footprint

Note: The meaning of FLAT, FLNG and BFOOT is being revisited to verify that the coordinates are indeed geodetic.


The geodetic (ellipsoidal earth) latitude of the 100 km geodetic altitude footprint, in degrees. Verified by calculating the IGRF field for the footprint position, and comparing with BFOOT, tested mainly on orbit 1761. Difference found to be < +/-20 nT. Assuming the footprint was geocentric gave larger differences, of the order 100's of nT.


The geodetic (ellipsoidal earth) longitude of the 100 km geodetic altitude footprint, in degrees. Verified by BFOOT comparison, tested mainly on orbit 1761.


Model field at FAST footprint, defined by tracing field lines to 100 km geodetic (ellipsoidal earth) altitude. Field given in GEI (Geocentric Equatorial Intertial) coordinates. Verified for orbit 1761, where difference was found to be < +/-20 nT. As noted above, FLAT and FLNG where also assumed to be geodetic latitude and longitude.

Note on geodetic coordinates:

The following parameters are used in the IDL procedure:
mean_earth_radius = 6371.2 ; mean radius of earth, in km
req = 6378.14 ; equatorial radius of earth, in km
rpo = 6356.76 ; polar radius of earth, in km
earth_flat_const = 1.006740 ; = 1 / (1 - f)^2, where f = 1/298.257 is the earth flattening factor


IGPP/UCLA Space Physics Center home page     IGPP/UCLA FAST home page     Bob Strangeway's home page

created by R. J. Strangeway.


Last modified: September 29, 2006.