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:
t2 are the start and stop times,
/all keyword means get all orbit parameters,
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 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
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
Orbit number, changes at ascending node, when z_gei of spacecraft crosses zero
from negative to positive.
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
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
ILAT: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
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.
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
$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.
$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`
/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).
mag4wi.dat contains the coefficients
for this version of the IGRF model. You can use this file to update the
$FASTCONFIG/Fastorb/mag4wi.dat, but this version will over-ride any future update in "delivery."
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
Note on geodetic coordinates:
The following parameters are used in the get_fa_orbit.pro 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.