This page was created by the IDL library routine
mk_html_help2.
Last modified: Mon Oct 20 03:17:44 2025.
FUNCTION: auroral_zone PURPOSE: IDL function to calculate auroral zone position as a function of magnetic local time (mlt: 0.0-24.0 hours), activity index Q (q: 0-6). Returns corrected geomagnetic colatitude in radians. OPTIONS: To return poleward edge, set poleward. To return latitude, set latitude. To return value for southern oval, set south. To return value in degrees, set degrees. See Holzworth & Meng, GRL 2, p. 377, 1975. Originally written by J. Clemmons, June 1993. Corrected by J.Rauchleiba under the direction of Mike Temerin Apr 1997.
(See general/missions/fast/fa_general/fast_orbit/auroral_zone.pro)
FUNCTION: auroral_zone_ssc
PURPOSE: Given an array of MLT values, returns latitudes of the
auroral zone boundaries. The definition of the
auroral zone is that used by the Satellite Situation
Center. It is basically the area between two
sinusoidally-perturbed concentric circles centered on
the magnetic pole.
Output is equatorward latitude in Geomagnetic
Coordinates, and in radians unles DEGREES is set.
ARGUMENTS:
MLTINPUT The input array of MLT values. Elements should look
like [0, .1, .2, ..., 23.9, 24.0]
KEYWORDS:
POLEWARD Set this to a named variable to receive the poleward
latitude values.
SOUTH Set this keyword to one if a reflection through the
magnetic equator is desired. This gives
S. Hem. coordinates.
DEGREES Set this keyword to get the coordinates in degrees,
otherwise output is in radians.
NOTES: The definition of the auroral zones used here is that
accepted by the SSC. See also: auroral_zone.pro.
CREATED: By Joseph Rauchleiba
98/1/6
(See general/missions/fast/fa_general/fast_orbit/auroral_zone_ssc.pro)
FUNCTION:
DATESEC_DOY
DESCRIPTION:
take args for year and day of year and return
(double float) seconds since 1 Jan 1970, 00:00 UT.
USAGE:
print, datesec_doy(75, 134)
gives result:
1.6925760e+08
NOTES:
does not handle years past 1999; year must be two digit.
REVISION HISTORY:
@(#)datesec_doy.pro 1.3 01/26/99
written by Ken Bromund, Space Sciences Lab, Berkeley. May, 1991
(See general/missions/fast/fa_general/fast_orbit/datesec_doy.pro)
FUNCTION:
DATETIMESEC_DOY
DESCRIPTION:
function to return seconds since 1/1/1970 00:00 UT, from date and
time given as day, month, year, hour, minute, second, millisecond.
USAGE (SAMPLE CODE FRAGMENT):
; set up a date and time (21 Mar '91, 00:01:01.000)
doy = 80
year = 91
hour = 0
min = 1
sec = 1
msc = 0
; convert to seconds
sec_date_time = datetimesec_doy(year, doy, hour, min, sec, msc)
; print it out
PRINT, sec_date_time
--- Sample output would be
669517261
NOTES:
If any of the fields are are out of range, the value will be carried.
e.g. given date and time of 31/12/90, 25:01:00.1001, this will be
converted to 1/1/91, 01:01:01: 001
If any of the input values are negitive, this is an error and -1 will
This function can return seconds of days, or seconds since 1970 only
by calling it with dates or times set to zero.
If input values are arrays, then an array of N_ELEMENTS(inputs vals)
of date strings and remainders will be returned. The number of
array elements for all input parameters must be the same
REVISION HISTORY:
@(#)datetimesec_doy.pro 1.2 01/26/99
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Sep. '91
Revised to handle arrays of input values, JML, Mar. '92
(See general/missions/fast/fa_general/fast_orbit/datetimesec_doy.pro)
FUNCTION: dipole_offset PURPOSE: Calculate the location of the dipole using the IGRF coefficients and their secular variation. IGRF coefficients are the coefficients used in the spherical harmonic expansion of the earth's magnetic field and there is a standard formula for converting the first few of these coefficients to dipole offset. This version is accurate for years 1995-2000 Returns a 3-element vector in kilometers. INPUT: Optional argument is 4-digit year Algorithm by: Mike Temerin Written by: J.Rauchleiba 4/8/97
(See general/missions/fast/fa_general/fast_orbit/dipole_offset.pro)
PROCEDURE:
label_foot_ticks
PURPOSE:
Keeps track of parasites on the pedal area of the body. Adds
timeticks and text labels to a path plotted on a map of the
earth. The latitudes and longitudes, as well as the
corresponding time array, must be passed through keywords. This
procedure was written for plot_fa_crossing.pro.
KEYWORDS:
TIME_ARRAY The time array corresponding to the FLAT and FLNG
arrays.
LATITUDE The latitude array.
LONGITUDE The longitude array.
LATLIM The absolute value of lattitude above which (below in
S. hem.) to confine timeticks on the plot. Default is
45 degrees.
INTERVAL The interval in seconds on which ticks are marked.
Default is 300 sec.
COLOR The color of the labels
CREATED:
BY J.Rauchleiba
DATE 97-9-12
(See general/missions/fast/fa_general/fast_orbit/label_foot_ticks.pro)
PROCEDURE: mag_to_geo PURPOSE: Converts lattitude and longitude between MAG and GEO coordinates. Uses a simple transformation matrix from Kivelson and Russell, "Intro to Space Physics" which is not very accurate in the polar regions. PARAMETERS: lat The array of lattitudes.(In radians unless degrees keyword set.) lon The array of longitudes.(in radians unless degrees keyword set.) KEYWORDS: degrees Set this if both input and output are to be in degrees. mag Set this to do the inverse transformation, GEO to MAG coordinates. Created by: J.Rauchleiba 1/7/97
(See general/missions/fast/fa_general/fast_orbit/mag_to_geo.pro)
PROCEDURE: plot_fa_crossing
PURPOSE:
Plots magnetic footprint of spacecraft across earth. (FLAT,FLNG)
Shows the night/day terminator, auroral ovals, apogee and perigee
footprints, etc. (See examples below.)
Keywords are grouped into categories: TIMESPAN, VIEW, DISPLAY,
AURORAL ZONE, MISCELLANEOUS.
TIMESPAN KEYWORDS:
ORBIT The orbit to plot. If unset, will plot over interval
containing present time and show craft position right now
(unless TMIN and TMAX are set). ORBIT cannot be greater than
the last orbit listed in the predicted orbit almanac file.
TMIN, TMAX Time points to be included on the chart. Use these if
you want to display timespan in distant future.
Should not be more than a couple hours apart. Format
of TMIN and TMAX must be the type of string accepted
by time_double() or a double float in seconds since
1970. ORBIT must not be set if these keywords are to
be used. These times will be labeled on the map as t1
and t2. (Good for showing AOS and LOS taken from
contact schedules.)
XMARK Set this to a time (string or double float) to have that point
labeled on the map as a big X. If none of ORBIT,
TMIN, TMAX are set then this time will be used as the
reference time for which to create the plot. (Good
for showing conjunctions.)
VIEW KEYWORDS:
KIRUNA, POKER, WALLOPS, MCMURDO, CANBERRA, SANTIAGO, BERKELEY:
Set any of these for an overhead view of the station.
VIEWPOINT This allows arbitrary views of the Earth. Should be a
3-element array designating lattitude, longitude, and
rotation in degrees.
WHOLE If set, will not confine plot to polar regions.
SOUTH Set to view earth from directly over South Pole.
MAGPOLE View from above the magnetic pole with magnetic local
noon at the top of the plot. Gridlines are still
geographic. Poles are not symmetric because of the
eccentric dipole. (When this keyword is not set
the display defaults to above the geographic poles,
with geographic local noon at the top.)
ZOOM Enlarges the map. 1 is normal, 2 is twice as big.
See WINSIZE keyword for zooming in postscript mode.
DISPLAY KEYWORDS:
WINSIZE The width of the plot window in pixels. Default width is
640. Height is scaled automatically so that lattitude
lines will be circular when output on a Tek printer:
H = W * 1.031. In PostScript mode (POST keyword set),
WINSIZE acts like a magnification factor; WINSIZE=10
is normal.
PC Set this to nonzero if you are using a windowing system
that does not provide backing store to retain hidden
windows. This keyword also sets the VECTOR_FONTS keyword.
GREY Set this keyword to output the plot in greyscale.
(Run @startup to restore colortable.)
FILL Fills oceans and continents with solid color to make a
pretty plot. Setting this keyword when printing to
a color printer is discouraged.
VECTOR_FONTS Disable switch to device (hardware) font from
(default) Hershey vector-drawn fonts. Device fonts
may be prettier, but vector fonts are device
independent.
POST Set this to a filename to direct the ouput to an 8-bit color
postscript file instead of the graphics window. When
viewing the postscript file, be sure your viewer is
set to 8 bits, not 24, and that it is displaying
"perfect colors". (Do not add ".ps" to the name.)
GIF Captures the image on the output graphics window to a
GIF file. (Add ".gif" to the name yourself.)
AURORAL ZONE KEYWORDS:
ACTIVITY Set the Activity Index of aurora. ( 0-6, default 3)
SSCZONE Show the auroral zone used by the Satellite Situation
Center instead of the one from Holzworth and Meng.
(THIS IS NOT PERFECTED YET.) See auroral_zone_ssc.pro
and notes below.
MISCELLANEOUS KEYWORDS:
POLAR Plots the magnetic footprint of the POLAR spacecraft
and information about its closest approach to that of
FAST. Good for finding conjunctions or displaying
known ones. (For a description of how POLAR orbit data
is obtained, see the documentation for
get_po_orbit.pro.)
DRAG_PROP If set, the orbit propagator will include the effects
of atmospheric drag. The orbit track may be
inaccurate by a few degrees for propagations as short
as a few weeks. This keyword minimizes this error.
ALMANAC_INFO Prints a line under the plot title telling the orbit
file used, the last epoch in that orbit file, and
whether or not drag was included in the orbit propagation.
EXAMPLES: Show what FAST is doing now, and make it pretty:
IDL> plot_fa_crossing, /fill
Show what FAST is doing for Christmas, make output
greyscale, and copy output to a GIF file:
IDL> plot_fa_crossing, xmark='98-12-25/00:00:00', $
gif='~/images/northpole.gif', /grey
Show the polar crossing of orbit 3000 from a
bird's-eye view over Canberra, and send the output to
an 8-bit color postscript file:
IDL> plot_fa_crossing, /can, post='~/images/orb3000', $
orbit=3000
NOTES ON THE
AURORAL ZONE: The auroral zone is drawn using a procedure by Jim
Clemens (suggested by Holzworth & Meng, and corrected
by Mike Temerin). The source for this procedure is
"Mathematical Representation of the Auroral Oval",
R.H. Holzworth and C.-I. Meng, Geophysical Research
Letters, Vol.2, No.9, Sept 1975.
The mathematical representation of the auroral ovals
is found by fitting Feldstein statistical ovals in
corrected geomagnetic coordinates to a 7-parameter
Fourier series:
theta = A1 + A2 cos(phi + A3)
+ A4 cos(2phi + 2A5)
+ A6 cos(3phi + 3A7)
theta = corrected geomagnetic co-lattitude
phi = 2(pi)(MLT)/(24hrs)
The best fit constants are found for each value of
Q=0..6, where Q is the activity index which describes
how quiet (0) or active (6) the Feldstein auroral
ovals are. The characteristic radius A1 of the ovals
increases monotonically with Q. (Source: Holzworth and
Meng.)
The function azonloc.pro generates the southern
auroral oval by reflection of the northern oval
through the magnetic equator.
The formula in Holzworth and Meng gives the ovals in
corrected geomagnetic coordinates. The procedure
transform_mag_geo.pro converts them to geograhic
coordinates using the eccentric dipole model.
CREATED BY: J.Rauchleiba 96-12-20
(See general/missions/fast/fa_general/fast_orbit/plot_fa_crossing.pro)
PROCEDURE: rerange PURPOSE: Reformats arrays so they may be plotted as lattitude and longitude. Changes arrays so that they are in the intervals [-pi/2, +pi/2] and [-pi, +pi]. Can change both lattitude and longitude or just longitude. ARGUMENTS: lng The longitude array in radians. lat The corresponding lattitude array in radians. (Optional) KEYWORDS: degrees Set this to return the arrays in degrees. Created by: J.Rauchleiba 12/20/96
(See general/missions/fast/fa_general/fast_orbit/rerange.pro)
FUNCTION:
SECOFDAY
DESCRIPTION:
Function to return seconds of a day, given the time in hours, minutes,
seconds and milliseconds.
USAGE (SAMPLE CODE FRAGMENT):
; set up a time (00:01:01.001)
hour = 0.
min = 1.
sec = 1.
msc = 1.
; convert to seconds
seconds = secofday(hour, min, sec, msc)
; print it out
PRINT, seconds
--- Sample output would be
61.001
NOTES:
If input seconds is an array, then an array of N_ELEMENTS(inputs vals)
of date strings and remainders will be returned.
The number of array elements for all input parameters must be the same
REVISION HISTORY:
@(#)secofday.pro 1.2 06/04/95
Originally written by Jonathan M. Loran, University of
California at Berkeley, Space Sciences Lab. Sep. '91
Revised to handle arrays of input values, JML, Jan. '92
(See general/missions/fast/fa_general/fast_orbit/secofday.pro)
PROCEDURE: terminator PURPOSE: Generates lattitude and longitude arrays for the night/day terminator given an input time. Values returned are in Geographic coordinates. KEYWORDS: TIME The input time in seconds since 1970. POSITIONAL PARAMETERS: TLAT The name of the array in which to return the lattitude values of the terminator. TLNG The name of the array in which to return the longitude values of the terminator Created by: J.Rauchleiba 97-25
(See general/missions/fast/fa_general/fast_orbit/terminator.pro)
PROCEDURE: transform_mag_geo PURPOSE: Convert lattitudes and longitudes between MAG and GEO coordinate systems using the eccentric dipole model. Transformation is from MAG to GEO unless INVERSE is set. Transformation is performed at <Re> + 100km = 6472.1 km INPUTS: LAT The input lattitude array. (Not altered) LNG The input longitude array. (Not altered) TLAT Named variable to accept transformed lattitudes. TLNG Named variable to accept transformed longitudes. KEYWORDS: YEAR The 4-digit year. DEGREES If nonzero, input and ouput in degrees. INVERSE If nonzero, tranformation is from GEO to MAG. NOTES: MAG --> GEO: When transforming from MAG to GEO, LAT and LNG are assumed to refer to points Re=6372.1 km from the earth's dipole center. (This does not necessarily place them on the surface of the earth.) The points are propagated to <Re> + 100km and then their coordinates are converted to the GEO system through a rotation followed by a translation. This procedure is inaccurate for points where field lines are nearly orthogonal to lines through the dipole center, i.e. near the equator. GEO --> MAG: When transforming from GEO to MAG, LAT and LNG are assumed to refer to points Re + 100km from the center of the earth. Since this one is simply the inverse of the above transformation, we do the inverse translation followed by the inverse rotation. Right now, the GEO to MAG transformation is less accurate than its inverse; it does not propagate along field lines during the translation to the dipole center. WRITTEN BY: J. Rauchleiba 4/14/97 ALGORITHM BY: M. Temerin, G. Kaplan, J. Rauchleiba
(See general/missions/fast/fa_general/fast_orbit/transform_mag_geo.pro)