IRIDFLAR v1.52 by Rob Matson - February 26, 1998
------------------------------------------------

IRIDFLAR is a PC DOS-based program that produces a chronologically sorted
list of all Iridium satellite flares visible from an observer's location
over a user-defined time period which meet all the user's constraints.
Constraints include:

     1.  Minimum satellite elevation angle
     2.  Maximum solar elevation angle (w/option for no constraint)
     3.  Maximum flare angle (the angle off-specular, a.k.a. the
         mirror angle)
     4.  Minimum flare brightnesses (day/night)


Inputs/Configuration File
-------------------------

As of version 1.5, control-parameter input to IRIDFLAR is menu-based.
Most parameters are the same as in earlier versions of IRIDFLAR.  The
advantage of the menus is that you don't have to re-enter parameters
that haven't changed since your last computation.  When you exit the
program, IRIDFLAR will update your configuration file with your final
parameter values.

As before, "IRIDFLAR.CFG" is the default configuration file.  If this
file is not present at run time, the program will set its own default
values.  If you wish to run with a configuration file of another name,
type that name following IRIDFLAR at run time:

C:\ IRIDFLAR myfile.cf1

In the above example, if "myfile.cf1" is not found, the program will
behave the same as if IRIDFLAR.CFG was not found.  Note that when a
configuration file is named on the command line, that file (whether
it exists or not) becomes the default *output* file for storing
configuration parameters.  (In version 1.5, you have the option of
changing the configuration output filename as often as you like, and
you can also exit the program without updating the configuration
file).

For upward compatibility, IRIDFLAR version 1.52 will recognize and
translate version 1.4, 1.5 and 1.51 configuration files.

Dates/times can be UTC or local time, controlled by a toggle in the
Date/Time menu.  There is no longer a separate flag for daylight
saving time.  North latitudes and east longitudes are positive; south
latitudes and west longitudes are negative.


Two-Line Element (TLE) File
---------------------------

The input TLE file can contain just Iridium satellite elements, or any
superset containing the Iridium satellites of interest.  The program
automatically searches for all Iridium satellites in your TLE file.
This file can also have a header in it (e.g. MOLCZAN.TLE); IRIDFLAR
will read past it.

Since new Iridium satellites are periodically launched, a method for
identifying and processing these new satellites was added in version 1.3.
This way, a new version of the program does not need to be released
for each addition to the Iridium constellation.  To flag any new Iridium
satellites in your TLE file, make sure the format of the name lines is
"Iridium XX ...", where XX can be any two characters.  These characters
will appear under the "Ir" column of the output.


Output
------

Output is to the screen and optionally to a disk file.  For each flare,
three lines are generated.  The first and third lines are the approximate
times that all constraints are first met and last met respectively.  The
second line in each triplet is the time of minimum flare angle and maximum
brightness.  (Occasionally two lines are output instead of the usual three.
This can occur if the sun makes a transition from below the sun angle
constraint to above it in mid-flare.)

In version 1.3, the option to output a single line per flare was added.
In this case, only the peak of each flare is output to screen and disk.
 

Screen Output
-------------

There are 14 values on each screen output line.  From left to right,
these are:

 1. Iridium satellite number (or 2-character code -- see paragraph above)
 2. Date in YY-MM-DD format.  Date is UTC or local depending on user input
 3. 24-hour time.  UTC or local, just as for Date.
 4. Satellite azimuth in degrees, measured east of north; East=90.
 5. Satellite elevation angle in degrees (a.k.a. altitude angle)
 6. Satellite range (in km)
 7. Node (A=Ascending, D=Descending)
 8. Satellite illumination condition.  Lit=Sunlit, or Pnb=Penumbra (sun
    has partially set as seen by satellite).
 9. Elevation of sun at observer's site (in degrees).  Negative when sun
    is below the horizon.
10. MMA (Main Mission Antenna) causing the flare.  Code: F=forward,
    L=left, R=right.
11. Flare angle (degrees).  This tells you how close the geometry is to
    satisfying a perfect specular reflection.  Any angle less than 0.25
    degrees leads to a direct reflection of some portion of the solar
    disk.  However, flares can still be seen when the flare angle is
    greater than 0.25 due to diffraction, atmospheric turbulence, and
    antenna surface contamination and imperfections.  Flare brightness
    falls off quickly with increasing flare angle; as a rule of thumb,
    the flare angle needs to be less than 2 degrees for the flare to
    reach 1st magnitude or brighter.
12. Visual magnitude.  This is a rough estimate of the flare visual
    magnitude based on the flare angle, the projected area of the
    antenna producing the reflection, and the satellite range.
13. Flare latitude (degrees).  The geodetic latitude of the current
    point on the earth that has a flare angle of exactly zero.
14. Flare longitude (degrees; negative is west, positive is east).
    The instantaneous longitude of the center of the flare.

The flare latitude and longitude tell you where the maximum flare is
occurring at that time.  As of version 1.52, the flare lat/long for
the middle line of each triplet is replaced with the ground distance
and bearing to the flare.  (Bearing is always east or west.)  This
tells you how far you need to drive in order to see the maximum flare.

While IRIDFLAR is calculating and displaying acceptable flares, you
can pause your display by hitting the space bar.  (Hit any key to
resume calculating).  The escape key can be used to terminate a
flare search in progress.


File Output
-----------

If you elect to produce an output file (in addition to the screen
output), then columns will also appear for the satellite right
ascension and declination, solar azimuth angle, flare peak magnitude
and flare standard magnitude.


Peak Magnitude and Standard Magnitude
-------------------------------------

In the "verbose" file output, the flare magnitude is immediately
followed by the peak magnitude and standard magnitude.  The peak
magnitude is an estimate of what the flare magnitude would be if you
were located at the coordinates listed for the flare latitude and
longitude (13. and 14. in the screen output).  From this location,
the mirror angle is zero, and the MMA reflects the exact center
of the sun (i.e. the brightest part of the sun).

The standard magnitude is only of use to modelers who are interested
in better defining the relationship between flare intensity and mirror
angle.  It does this by eliminating the two other variables that affect
flare brightness:  satellite range and MMA projected area.  The
standard magnitude indicates what the flare visual magnitude would
have been if the satellite was at a range of 1000 km, and the MMA
causing the flare was perpendicular to the observer-satellite vector.
The standard magnitude can differ significantly from the regular
magnitude when the satellite is either low in the sky (i.e. at long
range), or at a poor phase angle (MMA viewed edge-on), or a combination
of both.


Abbreviated Output File
-----------------------

In version 1.3, an option was added for producing abbreviated output
files.  This "brief" format has fewer output values (RA, Dec, peak
magnitude and standard magnitude are omitted), fewer digits of
precision, and more spacing between columns for better readability.
This format is intended for the more casual observer and was changed
in version 1.4 to include the solar azimuth.  An example appears below:


      Local          Iridium           Sun       Flare      Maximum Flare   Ir
  Date     Time    Azm El Rnge  N I  Azm Elv   Ang Mg MMA  Latit.  Longit.   #
------------------------------------------------------------------------------
98- 2- 5  5:01:20  184 29 1380  D L   95 -21   1.4  1  L   34.432 -118.115  35
98- 2- 5  5:01:32  184 27 1452  D L   95 -21   0.2 -7  L   33.766 -118.183  35
98- 2- 5  5:01:45  184 25 1527  D L   95 -21   1.3  1  L   33.078 -118.255  35


Satellite Orientation Errors
----------------------------

Paul Maley of NASA Johnson Space Center has reported that once each
Iridium satellite reaches its parking orbit, its orientation relative
to its velocity vector is maintained to within +/- 0.5 degrees in pitch,
+/- 0.4 degrees in roll and +/- 0.5 degrees in yaw.  If orientation
errors conspire in a worst-case fashion, the minimum flare angle
(a.k.a. mirror angle) for a particular pass can increase by as much
as 1.4 degrees (two times the rss of 0.5 and 0.5).  This could change
the brightness of a best-case pass by over 6 visual magnitudes (chang-
ing flare angle from 0 to 1.4).  The effect is not as severe for larger
flare angles; for example, a change from 1.0 deg to 2.4 decreases the
theoretical brightness by only 2.3 visual magnitudes.

Since the satellite orientation errors cannot be known apriori, it is
not possible to predict which flares will be absolute "show stoppers."
Of course, orientation errors can work for or against you.  A predicted
flare angle of 1.5 degrees could conceivable be improved to 0.1 degrees,
transforming a medium brightness flare into a -8 magnitude searchlight!


Anomalous Satellites
--------------------

At least three Iridium satellites have orientation errors which exceed
the above limits, causing unpredictable flare behavior.  These are
Iridiums 11, 21 and 27.  (Iridium 36 was previously unpredictable; it
is now reportedly stable.)  As of version 1.5, IRIDFLAR no longer makes
predictions for Iridium 27 since it has been determined that this
satellite is tumbling.  Iridium 27 can still produce bright flashes
when the geometry is right, with a period between flashes of about
3.6 seconds.  But until the rotation axis for the satellite has been
determined, the brightness of the flashes of future passes cannot be
predicted.  If a few observers at different locations can provide
dates and times when they have seen flashes from Iridium 27 brighter
than magnitude 0, I can perhaps determine a rotation axis.  (This
won't be a trivial problem since different observers could easily
be seeing flashes from different MMAs, or even from solar panels!)

Iridiums 11 and 21 are apparently a different story.  They may be close
to the proper flight orientation, but their orientation errors are much
greater than nominal.  This would cause these satellites to occasionally
flare as predicted by IRIDFLAR, but more often fail to do so.  To improve
your chances of seeing a flare from Iridium 11 or 21, I suggest relaxing
the mirror angle requirement to 10 degrees or more.  You will get a lot
of "false alarms", but you may also be rewarded by a bright flare when
a "dud" was predicted.


Internal Modeling Details
-------------------------

Orbital propagator:  SGP4
Earth geoid:  WGS-84
Earth equatorial radius:  6378.137 km
RA/Dec equinox:  Equinox of date
Refraction at ground site:  Included
Refraction at satellite:  Included


Revision History
----------------

Version 1.52
------------

Configuration file format changed to be more consistent with Windows
.INI files and SkyMap configuration files.  Program now reads parameters
from [IRIDFLAR] section of configuration file, and ignores any other
sections that may be present.  This allows users to add comments at
the beginning of their configuration files, or combine configuration
sections used by multiple programs.

Automatic recognition and translation of version 1.51, 1.5 and 1.4
configuration files.  If configuration file is not found or not
recognized, IRIDFLAR will ask for your latitude, longitude and time
zone hour, set the start date and time to match your computer's
current date and time (truncated hour), and set reasonable default
values for all remaining parameters.

Added City file support (a la SkyMap), so you can enter your site
name rather than coordinates, assuming it's in SKYMAP.CTY (or
whatever City File name you use.)

Batch-run support added.  If the line "Batch=Yes" appears in your
configuration file, then IRIDFLAR will use the settings that appear
in that file, calculate once, and exit.  In essence, the results
are the same as if you had run IRIDFLAR with that configuration
file, typed the <F10> key to calculate, and then hit the <ESC> key
to exit.

Ground distance and bearing (east/west) to the flare peak added.

Predicted flare magnitude equation modified slightly to better match
observed flares.  Version 1.52 now predicts brighter flares than
earlier versions when the mirror angle is greater than 0.25 degrees.

Better filtering of non-Iridium satellites.  Calculations will NOT
be performed for Iridium 27, Iridium Sim1, Iridium Sim2, or any
satellite whose name starts with "Iridium" but later contains a
slash.  (This eliminates unwanted predictions for Iridium rocket
bodies).

Previously, the ground coordinates given for each flare peak represented
"instantaneous flare ground-zero."  However, this is not quite the same
as the point along the flare-line *closest* to the observer.  The latter
is the more useful, since it tells you the minimum distance you need to
move in order to see the maximum flare.  (For most latitudes, this point
will be nearly due east or due west of your location).  So version 1.52
now calculates this point.  (Note that when displaying three lines per
flare, the first and third lines are still the instantaneous ground
flare point.  Only the middle line is the *closest* flare point to the
observer.)

Maximum mirror angle limit extended from 15 degrees to 30 degrees.

Minor output heading change ("FlrAng" replaced with "Flare" above
"Angle").


Version 1.51 (beta release only)
--------------------------------

Automatic recognition and translation of version 1.4 configuration
files.

Flag added to Date/Time Menu which, when set, will automatically load
the current date as the start date at initial run time.


Version 1.5 (beta release only)
-------------------------------

Maximum sun elevation parameter replaced by a sun-elevation day/night
transition point.  For passes that occur when the sun is LOWER than
this elevation, the program will filter out flares dimmer than the
nighttime magnitude limit.  For passes occurring when the sun is
HIGHER than the transition angle, the daytime flare magnitude limit
will be used.  For example, if you set the angle to -7 degrees, your
daytime flare magnitude limit to -4 and your nighttime magnitude
limit to +2, the program will find all flares brighter than mag -4,
and any flares brighter than 2nd magnitude when the sun is more than
7 degrees below the horizon.

Sequential input of user parameters replaced with menu interface.

Separate visual magnitude filters for daytime and nighttime passes.

Program modified to allow for the possibility of more than one flare
on a given pass (e.g. separate flares from the forward and left MMAs).

Predictions no longer made for Iridium 27.


Version 1.4
-----------

Minimum brightness visual magnitude filter added.

Federico Casazza discovered a bug which causes IRIDFLAR to get caught
in an endless loop if a satellite happens to enter the earth's umbra
shortly after a flare peak (and while still above the observer's
horizon).  This bug can also cause IRIDFLAR to miss flares under
other special circumstances.  Bug has been found and fixed.

Solar azimuth added to file output.

Peak magnitude added to screen output and verbose file output.

Standard magnitude removed from screen output; only appears now in
verbose file output.

Headers to output file have been expanded for easier understanding.

Minor bug fixed in the brief file output when "Does not intersect"
is supposed to appear.  Now replaced with "No intersection".

If seconds portion of time is less than 10, is padded with zero.

Magnitudes reported in brief-format output file now rounded to the
nearest integer magnitude (instead of truncated).

Formula for predicted magnitude versus mirror angle has been modified
slightly based on observed flare magnitudes.  Also, IRIDFLAR now
accurately models the radiance distribution of the solar disk (i.e.,
the center of the disk is brighter than the limb).  This causes
predicted flare magnitudes to continue to brighten as the flare
angle drops below 0.25 degrees.


Version 1.31
------------

Incorrect MMA identified in output.  Bug fixed.
Hard-coding of Iridium 42 name changed to Iridium 43.


Version 1.3
-----------

Method added for recognizing new Iridium satellites (see above).

Option added for (V)erbose or (B)rief output file format.

Option added for outputting 3 lines per flare or just the peaks.

Standard magnitude (1000-km range, square-on viewing) now calculated
to assist in refining the relationship between mirror angle and
visual magnitude.

Specific MMA causing each flare is now output under column "M".  The
codes are F-forward, L-left and R-right.  Directions are relative
to a "passenger" on the satellite facing in the direction of motion.

Special handling added for Iridium 11.

TLE file kept open only when running predictions (not while entering
parameters).  File-sharing of TLE file, configuration file and output
file now permitted (for multi-tasking environments).


Version 1.2
-----------

Added the maximum flare brightness location (latitude and longitude).

Eliminated screen output of right ascension and declination, and rounded
the satellite azimuth and elevation to the nearest degree to make room
for the flare latitude and longitude.  R.A. and declination are still
output to the file, though.

Eliminated handling of Iridium dummy satellites since these do not
have the highly reflective main mission antennae that the operational
Iridiums do.

Improved the flare search algorithm, greatly speeding up the program!


Version 1.1
-----------

Change MM-DD-YY output to YY-MM-DD.

Indicate in the longitude prompt that east longitudes are expected.
Have added "(- for W, + for E)".

Refraction now included when calculating sun and satellite horizon
coordinates.

Changed default configuration filename from IRIDDEF.DAT to IRIDFLAR.CFG.
Configuration filenames other than IRIDFLAR.CFG are allowed.

TLE filename is now included as one of the defaults, and it can be
changed between runs (just like all the other inputs).

Header added to output file with location coordinates, UTC offset, 
TLE filename, and configuration filename.

Non-integer timezones are now permitted (e.g. Australia).

Improved calculation of satellite lighting condition.  Now calculates
lighting the same way that SkyMap does -- 15 km or 20 km tangent height
extinction (depending on season), with 0.2 or 0.1 degrees of refraction
respectively.  (Version 1.0 incorrectly assumed that the sun was visible
from the satellite all the way down to the hard earth, where refraction
is about 1.2 degrees.  This was far too optimistic, leading to an
erroneous extension of sunlit times.)  Only two lighting conditions now
possible in IRIDFLAR output:  Lit or Pnb.

Start times can now be in any of the following formats:  HH:MM:SS,
HH:MM, or HH, where HH, MM and SS can be one or two digits.

Problem fixed with chronological sort intermixing output lines of two or
more satellites that happen to be flaring at approximately the same time.


Version 1.0
-----------

[Original release]
