Media Share 9/MEDIASHARE_09.ISO/hamradio/quicks24.zip/QUICKSAT.DOC

Text File | 1992-07-25 | 27KB | 677 lines

            QuickSat Satellite Prediction Program
                Version 2.4    July 25, 1992


This program has gradually evolved over many years.  Its purpose has always
been to support visual observations of satellites.  For that reason, the
normal execution of the program produces a single prediction for each
satellite.  That prediction point is the culmination point if that point
is outside the Earth's shadow.  Otherwise, a point outside the Earth's
shadow that is nearest the culmination point is chosen.  The prediction of
an object's magnitude is a primary goal.  The probable error in time of
prediction is computed by a heuristic.  The observer's comments may be
added to the 'intrinsic magnitudes' file for an object so that they will
be printed with subsequent predictions.  However, there is a "radio"
predictions flag that will bypass all of the parts of the program having
to do with magnitudes, the earth's shadow, RA and Dec.

The program is written in Fortran and uses the Microsoft Altmath Library.
This gives sufficient accuracy and the greatest possible speed for
computers which do not have a math coprocessor.  However, the use of this
library means that a coprocessor will not be used even if it is available.

The program has certain 'built-in' limits:  1) No more than 1100 names and
sizes may be read from the 'intrinsic' magnitudes file.  2) No more than
1000 element sets may be stored from the orbital elements files.  The
program requires an IBM compatible computer.  The program uses about 320K
bytes of memory.

The following files are provided:
1. QUICKSAT.EXE - the executable
2. QUICKSAT.MAG - a file of intrinsic magnitudes and sizes
3. QUICKSAT.CTL - an input test control file
4. QUICKSAT.DAT - an input test elements file
5. QUICKSAT.REF - the output file from the test
6. QUICKSAT.DOC - this file

The author of the program is Mike McCants.  I can be reached on the
Celestial BBS or at [e-mail] on the Internet.  My home address is
5105 Crestway Dr., Austin, TX 78731.  My home phone is [phone].



        Operation of the Program


The user operates the program in the following way:

I. Data preparation
   1. Orbital elements are obtained.
   2. Optionally, names, intrinsic magnitude, sizes, or comments
      are added to the 'intrinsic magnitudes' file.

II. Control file preparation
   1. The control file is edited to specify the year, month and day (or zero)
      and location for predictions and other prediction parameters.

III. Program execution
   1. The program is executed.
   2. If the control file is not named QUICKSAT.CTL, then the program prompts
      for its name and the user must enter the name.
   3. As determined by the control file, the user may be requested for the
      day of the month for the desired predictions.
   4. As determined by the control file, the user may be requested for the
      name of the file to contain output.
   5. As determined by the control file, the user may be requested for the
      name of a file containing orbital elements.

IV. After the program completes, the output file may then be printed or
    displayed.

The program operates in the following way:

1. The control file is read.
2. The orbital elements are read into memory.
3. The intrinsic magnitudes data is read into memory.
   (Note: the program will continue even if this file is not present.)
4. The predictions for a day are generated.
5. The predictions are sorted into time order and written to the output file.
Steps 4 and 5 are repeated for subsequent days.



        Description of the Documentation


The documentation consists of the following parts:

1. How to run the test
2. Description of the control file
3. Description of the intrinsic magnitudes file
4. Description of the orbital elements file
5. Description of the prediction output



        How to Run the Test


1. Enter QUICKSAT to execute the program.
2. Compare the generated file, OUTPUT.TXT to the reference file, QUICKSAT.REF.
Note:  Of course, lower case may be used, upper case is shown here for
clarity.



        Description of the Control File


This file controls the operation of the program.  The default name for this
control file is QUICKSAT.CTL.  If a control file by this name exists, it will
be used.  If not, the user will be prompted to enter the name of the control
file.

There are at least 18 lines in this file.  Each will be described in turn.

NOTE:  Each line has a 'fixed' format.  The format is shown with a preceding
line that shows which column positions must be used.  Comments may be placed
after the data values.  Because 'fixed' formats are being used, any error in
input could cause a bad value to be used or abnormal termination with a
'cryptic' Fortran error message.

Example test input control file (QUICKSAT.CTL):

 1990  7 Year, month number
 26  0 Start date, end date
 -0.3 -5.5 Start time, end time
   30.3340   97.7600      520.    5105 Crestway Dr.
 -5 CDT correction and time zone name for UT to CDT
 F True means generate Radio predictions
 2000 Epoch of predicted RA, Dec
  6.5 Magnitude limit
 15 Altitude cut-off value
 1.0 The search/step parameter value
 T True means accept only the most recent elements for each object
 F True means ignore shadow test
 T  1 True means generate multiple prediction points, how many each way
 T True means output distance values in miles
 T True means generate a blank line before each object's prediction.
quicksat.mag Intrinsic magnitudes input file
output.txt   Output file
quicksat.dat Elements input file
EOF          End of input file list


Line 1:  This line gives the year and month number.

12345678
 1990  7 Year, month number


Line 2:  This line gives the dates for prediction.

123456
 26  0 Start date, end date

The first number is first day for predictions, the second number is the
last day for predictions.  An end date of zero means perform predictions
for only one day.  If the start date is specified as zero, the user will
be prompted and asked to supply a start date from the terminal.  In this
case, predictions for only that day will be performed.

NOTE:  Due to the way the date is used in the program, the user must
always enter the date which ends at midnight.  For example, July 26,
1990 was a Thursday.  The predictions will be for Thursday evening and
Friday morning.  The title, "July 26  Thu evening", will appear at the
top of the predictions.  The user should always double check to make
sure that a one day error is not being made.

Note:  This is not the case if the "radio" predictions flag is set.


Line 3:  This line specifies the prediction time limits.

1234567890
 -0.3 -5.5 Start time, end time

The prediction time limits values are in hours.  A negative number means
'before', a positive number means 'after'.  If "radio" predictions mode
has not been specified, the reference times are the times that the sun
is 10 degrees below the observer's horizon.  Therefore a value of -0.3
means begin predictions 18 minutes before the time that the sun is 10
degrees below the observer's horizon in the evening.  A value of -5.5
means end the predictions at the time which is 5 hours 30 minutes before
the time the sun is 10 degrees below the observer's horizon in the morning.
These reference times are printed (in UT) as part of the output title.

If "radio" predictions have been specified, then these times are relative
to zero hours UT.  That is, -5.0 +2.0 would be a 7 hour span beginning
5 hours before 0 hours UT and ending 2 hours after 0 hours UT.


Line 4:  This line gives the latitude, longitude, height, and site name
of the observer.

         1         2         3         4         5
1234567890123456789012345678901234567890123456789012345
    30.334    97.760      520.    5105 Crestway Dr.

The site name text extends from column 32 to column 55.
The longitude is positive for west longitude, negative for east longitude.
Height is in feet.


Line 5:  This line gives the UT correction value and time zone name.

1234567
 -5 CDT correction and time zone name for UT to CDT

If a zero value is given, UT output from 0 to 23 hours will be output.

If a non-zero value is given, this value will be ADDED to the UT time of
prediction to produce a local time of prediction.  If the resulting value
is zero or negative, 24 will be added to make it greater than zero.  If
the resulting value is greater than 12, 12 will be subtracted.  Therefore
the predicted time will always have an hour value between 1 and 12.
If the time was originally 12 or greater and not 24, then the designation
PM will be printed with the time zone.  There is an adjustment of the
date printed above the predictions.


Line 6:  This line gives the "radio" predictions flag value

12
 F True means generate Radio predictions

If this flag is false, then the normal visual predictions will be generated.
If this flag is true, then "radio" predictions will be generated.  There
is no output of magnitude, shadow height, RA, Dec, or hour angle.


Line 7:  This line gives the epoch of the RA and Dec values.

12345
 2000 Epoch of RA, Dec


Line 8:  This line gives the 'cut-off' magnitude.

12345
  6.5 Magnitude limit

Any prediction whose magnitude is fainter than the 'cut-off' magnitude
will be suppressed.  If the intrinsic magnitude of an object is unknown,
then it is assumed to be 4.0 for this magnitude limit test.


Line 9:  This line gives the altitude 'cut-off' value.

123
 15 Altitude cut-off value

Any prediction which has an altitude below this 'cut-off' value will
be suppressed.


Line 10:  This line has the search/step parameter value.

1234
 1.0 The search/step parameter value

This parameter value is used as a 'stepsize' value in two situations.
If multiple points of prediction are specified, this value gives the step
size between each.  If a single prediction point is desired, but the
culmination point is inside the Earth's shadow, then this value gives the
step size for the search for a point that is not within the Earth's shadow.

If multiple points of prediction are specified, this parameter should be
adjusted to provide the desired spacing between the points.  A value of 1.0
will give the following results:  For an object at 400 miles, about a 1
minute spacing.  For an object at 600 miles, about a 1:30 spacing.  For an
object at 1000 miles, about a 2 minute spacing.

If multiple points of prediction are not specified, this parameter is only
used to search for a position that is at least 20 miles outside of the
Earth's shadow.  Thus a smaller value would require more computation, but
would often find a point higher in the sky that has a shadow height of more
than 20 miles.


Line 11:  This line has the multiple elements reject flag.

12
 T True means accept only the most recent elements for each object

If this flag is false, all elements in all input files will be accepted
for predictions.  If this flag is true, each element set will be checked
to see if it is for the same object as an element set already read in.
If so, then this element set will be discarded if its epoch is less than
or equal to the data already read in.  If its epoch is later, then this
element set will supersede the older one.  Thus only the latest data for
each object will remain for prediction purposes.


Line 12:  This line has the shadow test flag.

12
 F True means ignore shadow test

If this flag is false, no prediction will be generated for any point
where the height of the object is less than 20 miles above the Earth's
shadow.  If this flag is true, such prediction points will not be
suppressed, so predictions inside the Earth's shadow will be generated.


Line 13:  This line has the multiple points flag and the limit on the
          number of points that will be generated.

12345
 T  1 True means generate multiple prediction points, how many each way

If this flag is false, only one prediction point will be generated for each
pass of each object.  If this flag is true, multiple points may be generated.
Each point must satisfy the shadow test, altitude cut-off, and magnitude
cut-off.  The time difference between the points is determined by the step
size parameter value and the object's mean height.  The number in columns
3 to 5 is the limit on how many points can be generated 'on each side' of
the culmination prediction.  In the normal case, a value of 1 will generate
3 prediction points - the culmination point and one point both before and
after it.  However, if the culmination point is in the Earth's shadow, then
only one point will be generated.  Similarly, a value of 2 would normally
generate 5 points, but could generate only 1 or 2.

Note: a value of 0 or 99 means 'no limit'.

Note: the stepsize parameter is the value on line 10.


Line 14:  This line specifies the miles/kilometers flag.

12
 T True means output distance values in miles


Line 15:  This line specifies the blank line flag.

12
 T True means generate a blank line before each object's prediction.


Line 16:  This line specifies the intrinsic magnitudes input filename.

123456789012
quicksat.mag Intrinsic magnitudes input file

This file contains information on the name and intrinsic magnitude of
objects.  Comments may be retrieved for display with any prediction.
The physical size may also be included.  If this file is not found,
a message will be printed and no such data will be available.
(See further description below.)


Line 17:  This line specifies the output filename.

123456789012
output.txt   Output file

The name of the output file may be specified.  Alternatively, the
keyword 'prompt' may be specified in columns 1-6 in lower case.
Columns 7-12 must be blanks.  In this case, a prompt message is issued
at the terminal and the user must enter the output filename.


Line 18:  This line specifies the first orbital elements filename.

123456789012
quicksat.dat Elements input file

The name of the first elements file may be specified.  Alternatively,
the keyword 'prompt' may be specified in columns 1-6 in lower case.
Columns 7-12 must be blanks.  In this case, a prompt message is issued
at the terminal and the user must enter the elements filename.

The elements file may contain elements in two forms:  (1) An object name
line (up to 14 characters) followed by a standard set of two line elements,
(2) A 'one-line' set of elements.  (See further description below.)

Note:  Any element set with a mean motion less than 4.0 will be ignored.

Subsequent lines:  Additional orbital elements files.

If the keyword 'prompt' is not present on line 17, then additional input
files may be specified on subsequent lines.  The end of the input file
list is specified by either the physical end of the control file or a line
which contains 'EOF' in columns 1-3 in upper case.



        Description of the Intrinsic Magnitudes File


This file contains information about satellites.  The 'name' line for
each object may be followed by a 'size' line or an 'observation' line.
Other lines may appear.  Any line which does not begin with an 'n', 's',
or 'o' will be ignored.


The format of the 'name' line is:

         1         2         3
123456789012345678901234567890123456789
n catno f desig...  name.......... mag.
n 00005   58 B2     Vanguard 1      8.0

Column 1 contains the letter 'n'.

Columns 3-7 contain the NORAD catalog number.

Column 9 contains a non-blank character if there is a good reason why this
data does NOT need to be stored by this prediction program.  The use of the
letter 'd' to indicate that the object has decayed, or the use of the letter
'h' to indicate that this object has a high altitude orbit are appropriate.
The object is not counted against the limit since the data are not saved.

Columns 11-18 contain the 'designation'.  This information is not saved
by this prediction program.

Columns 21-34 contain the satellite name.

Columns 36-39 contain the intrinsic magnitude, which is defined to be the
maximum apparent brightness of the satellite when it is seen at full phase
at a range of 1000 kilometers.  The program will adjust this value according
to the actual circumstances of the prediction to determine a maximum possible
apparent magnitude.


The format for a 'size' line is:

123456789012345678901
s  7.4  2.4  0.0

Column 1 must contain the letter 's'.  The three numbers are the size values.
Most of the values given in the file were obtained from data posted to the
Canadian Space Society BBS by Ted Molczan.  He normally obtains these values
from the RAE Tables.  I have "adjusted" some of the values to bring the
computed intrinsic magnitude into better agreement with my observations.
If there is only one value, the object is assumed to be a sphere and the
value is its diameter in meters.  If there are two values, the object is
assumed to be a cylinder - the first value is its length and the second
value is its diameter.  If there are three values, then the object is
assumed to be rectangular and the values are its three sides.


The format for an 'observations' line is:

         1         2         3         4
123456789012345678901234567890123456789012
o observational information

Column 1 must contain the letter 'o'.  Columns 3-42 contain the observa-
tional comments.  These comments will be printed above each prediction.

The file supplied with the program may have the following comments:
1. per nnn - the tumble period in seconds.
2. SMax - the light curve has a 'secondary maximum', the tumble period
          given is from primary maximum to the next primary maximum.
3. var nnn - the object is sometimes fainter than its maximum brightness
             by the specified value (in magnitudes).
4. fl nnn - the object sometimes 'flashes' and increases brightness
            by the specified amount.
5. fl to nnn - the object has be observed to 'flash' up to the given
               magnitude.
6. sl tumb - the object tumbles slowly.



        Description of the Orbital Elements File(s)


Such a file contains orbital elements data.  The primary input is in the
form of two-line elements where each is preceded by the satellite name.
A secondary form is called 'one-line' elements.

Examples of two-line elements:

Alouette 1
1 00424U 62B-A  1 90192.70736421  .00000170  00000-0  19423-3 0  3322
2 00424  80.4633 261.8991 0022426 207.0003 152.9977 13.67365462386044
ATS 3
1 03029U 67111  A 90194.54223643 -.00000074  00000-0  99999-4 0  3953
2 03029  13.2438  21.0153 0013818 204.7992 155.1757  1.00272749 83052
Cosmos 398
1 04966U 71 16  A 90200.49713217  .00042980  17752-4  27181-3 0  9862
2 04966  51.5262 157.4892 2249896 208.4414 137.3099 11.10705110595285

The name field is read, but is only used when no 'name' entry appears in the
intrinsic magnitudes file.

Note that only 14 characters of a name field will be remembered.  This
means that there is a chance that an object and its rocket body may
have the 'same' name if the first 14 characters are the same.

Note:  There is no attempt to check the 'check-digit' value.

Note:  The drag term which appears after the epoch is used.  The change in
the drag term value is not used.  The Bstar term is not used.

Note:  The ATS object is discarded because its mean motion is less than 4.

If it is desired to input orbital data in the 'one-line' form, then the
following line must appear before this data:

ONELINE

The following form must be used for 'one-line' data:

         1         2         3         4         5         6
123456789012345678901234567890123456789012345678901234567890
nnnnnyydddffffffddddddiiiiiinnnnnneeeeeeaaaaaammmmmmxxxxxxxx
206399019071772000014705251829684400765901146334880715202450

Columns 1-5 is the NORAD catalog number.
Columns 6-7 is the year.
Columns 8-10 is the day number.
Columns 11-16 is the fraction of a day.
Columns 17-22 is the drag term.  (Implied decimal left.)
Columns 23-28 is the inclination.  (Implied decimal in the middle.)
Columns 29-34 is the ascending node.  (Implied decimal in the middle.)
Columns 35-40 is the eccentricity.  (Implied decimal left.)
Columns 41-46 is the argument of perigee.  (Implied decimal in the middle.)
Columns 47-52 is the mean anomaly.  (Implied decimal in the middle.)
Columns 53-60 is the mean motion.  (Implied decimal 2 from the left.)

Example:

206399019071772000014705251829684400765901146334880715202450

The following values are read:

20639 is the catalog number.
90 is the year.
190 is the day number.
.717720 is the fraction of a day.
.000147 is the drag term.
52.518 is the inclination.
296.844 is the ascending node.
.007659 is the eccentricity.
011.463 is the argument of perigee.
348.807 is the mean anomaly.
15.202450 is the mean motion.

The input of elements in this form may be terminated by a line which
contains a zero for the catalog number.



        Description of Satellite Prediction Output


The first line is an 'echo' of some of the input values from
the control file:

  30.334  97.760  520.    5105 Crestway Dr.     2000  6.5 15 F F T T T

The latitude, longitude, height, and site name are listed.  The epoch
of RA and Dec is given.  The magnitude cut-off and altitude cut-off
are given.  Five true/false flags are given.


The next line gives the date and time zone:

***  1990 July 26  Thu evening  *** Times are PM CDT ***   215 1058

For the prediction date of July 26, the evening predictions are for
Thursday.  The predictions times are PM for the time zone CDT.  The
value 215 is the UT time of twilight when the sun is 10 degrees below
the horizon.  The value 1058 is the UT time of morning twilight when
the sun is 10 degrees below the horizon.


The next line gives the titles for each data line:

 H  M  S  TIM AL AZI C   U  MAG   REVS  HGT SHD  RNG  EW PHS  R A   DEC

Each of these fields will be discussed below.


Before each prediction, the object header line is given:

20625 Cos 2082 Rk   10.4 3.9     2.5   2.0  var 2.5 per 22 incr


The NORAD catalog number is given.  The name is given.  The three size
values and the computed intrinsic magnitude at full phase and 1000 Km
(derived from the sizes) are given if they are available.  The observed
intrinsic magnitude is given (if available).  Finally, the comments field
from the intrinsic magnitudes file is given (if available).


Each set of predictions has the following form:

 H  M  S  TIM AL AZI C   U  MAG   REVS  HGT SHD  RNG  EW PHS  R A   DEC
 9 42  2   .3 37 264    30  4.0  443.4  536 493  816 0.9 116 1250  13.0
 9 43 22   .3 41 297 C  35  3.9  443.4  536 498  758 1.0 123 1234  38.7
 9 44 41   .3 35 328    40  4.3  443.4  536 503  840 1.0 124 1148  62.9

The time is UT unless a non-zero correction was specified in the input
file.  In the current example, -5 was specified to convert UT to CDT.

The TIM value is the estimated uncertainty in the time of prediction
(in minutes).  So, .3 is 18 seconds "likely" error in the prediction.

The AL value is the altitude of the prediction point.
The AZI value is the azimuth of the prediction point.
The letter C after the azimuth indicates that this is the point of
culmination.  The absence of the C would indicate that this is not a
culmination prediction.

The U value is the number of degrees the satellite has covered in its orbit
plane since its last equator crossing from south to north.  It is thus an
indication of whether the satellite will be moving south to north, north to
south, or west to east.  In this case, the satellite has gone only about
35 degrees since it crossed the equator and is going from southwest to
north.

The MAG value is the predicted maximum magnitude if an observed intrinsic
magnitude was avaliable.  This does not mean that the satellite cannot be
brighter or fainter than this magnitude.  The satellite can be brighter
if it reflects the sun better than expected at this phase angle.  It can
be fainter than expected if it reflects the sun worse than expected at
this phase angle or if it is a non-circular object and its particular
attitude is unfavorable on this pass.  Since the comment "var 2.5" appears,
then it is likely that the object can change in brightness from this
"maximum predicted magnitude" to a brightness that is 2.5 magnitudes
fainter.  Usually such a variation will take place in less than 2 minutes.
If "var att" appears, then the object varies very slowly and is usually
constant at some brightness equal to or less than the prediction.

If an observed intrinsic magnitude is not available, then the special value
"20" is used for the intrinsic magnitude.  This will normally produce a
predicted magnitude between 18 and 24.  If the observer has an expection of
the intrinsic brightness because of a knowledge of the expected size, then
this "20" magnitude can be transformed as follows: 20 is subtracted and the
expected intrinsic magnitude is added.  For example, if 20.4 appears, but
the observer expects an intrinsic magnitude of 3.5, then 20.4 - 20 + 3.5 =
3.9 and the expected magnitude is 3.9.  If the object is observed to be
about 4.4, then an intrinsic magnitude of 4.0 would be appropriate.

 H  M  S  TIM AL AZI C   U  MAG   REVS  HGT SHD  RNG  EW PHS  R A   DEC
 9 42  2   .3 37 264    30  4.0  443.4  536 493  816 0.9 116 1250  13.0
 9 43 22   .3 41 297 C  35  3.9  443.4  536 498  758 1.0 123 1234  38.7
 9 44 41   .3 35 328    40  4.3  443.4  536 503  840 1.0 124 1148  62.9

The REVS value is the number of revolutions the object has made since
the perigee that preceded the epoch of the elements.  A fractional value
of .0 indicates that the object is at perigee.  A fractional value of .5
indicates that the object is at apogee.  A value of .2 indicates the
object is rising from perigee to apogee.

The HGT value is the height of the object in miles or kilometers.

The SHD value is the height of the object above the Earth's shadow.

The RNG value is the range of the object.

The EW value is the distance east/west that the orbital plane moves in
one minute.  If this satellite is one minute early, it will be 1.0 degrees
to the east of the predicted position.  If it is one minute late, it will
be 1.0 degrees west of the predicted position.

The PHS value is the sun-object-observer angle.  A value of 0 indicates
full phase, a value of 180 indicates new phase.  This is the opposite of
the proper definition of phase angle.

The R A value is the Right Ascension of the prediction.

The DEC value is the Declination of the prediction.

If a "radio" prediction is requested, then the output would look like:

 H  M  S  TIM AL AZI C   REVS  HGT  RNG
20625 Cos 2082 Rk     var 2.5 per 22 incr
 9 42  2   .3 37 264    443.4  536  816
 9 43 22   .3 41 297 C  443.4  536  758
 9 44 41   .3 35 328    443.4  536  840