This page was created by the IDL library routine
mk_html_help2
.
Last modified: Thu Aug 6 12:53:14 2020.
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 str_to_time() 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)