SKY-CALC & SKY-CALENDAR

General purpouse utilities for astronomical calculation are available on
Vax ASTBO1 computer at IRA.

To start the commands you must enter:

	$ SKYCALENDAR    --->    Almanac on screen 
        $ SKYFILE        --->    Almanac in file SKYFILE.DAT
        $ SKYCALC        --->    Astronomical calculator 



--------------------------- USER MANUAL --------------------------------

	0. INTRODUCTION

This document describes two programs.  One is an INTERACTIVE
astronomical circumstances calculator, which is a powerful
general-purpose utility.  The other prints a
1-year nighttime CALENDAR of phenomena for a single site; this
will generally be run in background, to produce a table to be
hung on the observatory wall.

Both programs, in their original manifestations, were coded as
standalone c programs by John Thorstensen at Dartmouth College.
The programs should be transportable to other sites with a minimum
of effort ... but do read the documentation!


	1. THE INTERACTIVE ALMANAC

	This program is designed to provide quick and easy access to
astronomical quantities of interest to an observer at the telescope,
and to expedite the planning of (especially nighttime) observations.
it is designed to supplant some functions of the  'Astronomical Almanac',
and get around the need for interpolating some of its tables.  It
also allows one to reconstruct after the fact such information as
the extent to which moonlight might have interfered with
an observation, the corrections to the solar system barycenter,
and so on.  The original code was written as a self-contained
program in the c language, for maximum portability.
The description here has two main parts; the first describes
the operation of the program, and the second gives details of
the algorithms used (including sources where applicable) and some
estimations of their accuracy.


** NOTE: This part of the documentation tells you how to use the program.
   Before using it for purposes where accuracy is critical, or for
   locations at extreme geographical positions, it's a good
   idea to read up on the algorithms and their limitations.  And it's
   always the user's responsibility to be sure their answers are sensible.
   Be especially careful when the code is recompiled on your local machine;
   experience shows that compilers can generate different answers from
   the same code.  The examples below can be used to check that
   your local compiler gives the correct answers.
   With these caveats, we proceed to.... **


	     USING THE PROGRAM.

	When the program is run, it describes the default site
for calculations.  Whoever installed the program should have set this
default site to the one you're likely to use.  Check to see that it
is the site you want; if not, you can change it immediately.  A little
menu comes up with the 'canned' sites which have been installed; give
the single character for the option you want.  Here's what the whole
thing should look like, though you'll probably have more menu options:

	Astronomical calculator program, by John Thorstensen.

	Default site is Kitt Peak
	Longitude  7 26 28 (hms) West, latitude  31 57.2 (dms) North
	Standard time zone  7 West of Greenwich

	You can change it now if you want:
	*SELECT SITE* - Enter single-character code:
	   x .. exit without change (current: Kitt Peak)
	   k .. Kitt Peak
	   s .. Shattuck Observatory

... (and so on ... several different sites are available) ...

	   Any other char .. OTHER (You'll be prompted for params.)
	Your answer --> Your computations will be for Kitt Peak


If the desired site is not on the menu, type any character
other than the ones on the menu, and you'll be prompted for the
characteristics of the site.  The prompts should be fairly
self-explanatory.  Note that the longitude and time zone are
POSITIVE WESTWARD, unlike the Almanac convention.  Also, longitude
is in HOURS minutes and seconds, and latitude in DEGREES minutes
and seconds.

The program now prompts you for a date, with the prompt:

	Evening Date (yyyy mm dd; give negative year to exit):

Your answer might be, for instance

	1990 10 20

for 1990 October 20.  Given this, it now prints a list of
phenomena for the night you specified.  Note that the date you have
given is the *local* date for *evening*.  The output should look
like this:

	Almanac for Kitt Peak:
	long.  7 26 28 (h.m.s) W, lat.  31 57.2 (d.m.s) N.
	Mountain Standard Time in use all year.

	local evening date : 1990 Oct 20, Sat
	local morning date : 1990 Oct 21, Sun
	UT date at civil midnight: 1990 Oct 21
	Julian date at civil midnight  : 2448185.791667

	LMST at civil midnight:  1 31 23.7
	Sunset:   17 49 MST; Sunrise:    6 34 MST
	Evening twilight:   19 10 MST;  LMST at evening twilight:  20 40 44
	Morning twilight:    5 13 MST;  LMST at morning twilight:  6 44 50

	Moonset :   18 50 MST
	Fraction illuminated at civil midnight:   0.064
	Moon coords. at midnight(+-0.3deg):  15 32.7,  -24 03

	Now entering 'calculator' mode; the documentation is on
	line.  I suggest you read it all at some point.
	Type command, ? for a menu, or q to quit this mode:

Note that times of moonrise or moonset are reported only if they occur
'at night', that is after roughly 16h local time or before 8h local time.
The moon position is given for local midnight, whether or not the moon is
actually up at the time.

After this, the program goes into a 'calculator mode' which
lets you change parameters one by one and look at circumstances of
observation for the specified parameters.  Typing ? will give you
a menu; it looks like:

	Circumstance calculator; single char commands:
 	 ? .. print this menu.
 	 x .. print eXamples
	 l .. print CAUTIONS and LEGALITIES
	 a .. print Accuracy/Algorithm info.
	 q .. QUIT .. returns to almanac mode.
	** INPUT OPTIONS: ** (Note formats.)
	 r .. enter object Ra (hh mm ss, for ep.).
	 d .. enter object Dec.(dd mm ss, for ep.)
	 e .. enter Epoch of input coords(default is 1950.)
	 p .. enter object Proper motions (answer prompts).
	 y .. enter date, starting with Year (yyyy mm dd)
	 t .. enter time (hh mm ss)
	 g .. *toggles* whether times entered are Greenwich or local
	 s .. change site parameters; prompts for all of them
	** OUTPUT OPTIONS: **
	 = .. PRINT CIRCUMSTANCES -- (most frequent)
	 c .. show galact and eclipt coordinates
	 h .. make hourly airmass table (answer prompts)

Most parameters are entered as a single character followed by
the value of the parameter.  For instance, to enter an RA, you
type

	r 8 34 14


Typing an = causes the current circumstances to be printed out.

There is no prompt given, which can be disconcerting but allows
one to enter all sorts of stuff at once without generating
lots of annoying 'fossil prompts'.

Typing the letter q *quits* the calculator mode.  You
get prompted for another date, to generate another
nightly almanac if you wish;  you can exit by giving
a negative number like -1.

Note that times, right ascensions, and declinations are
entered as *triplets of numbers* separated by 'whitespace'
characters (blanks, tabs, or newlines).  Any of the numbers can have a
fractional part; for instance, RA 19h 20m 00s could be entered as

	r 19.33 0 0

(The trailing zeros may or may not have to be there; experiment with
your local implementation).  To enter a negative declination, just
make the first number negative, as in

	d -0 18 30

(-0 is correctly handled to give a negative declination.)

Note that the letter y is used to signal that the date follows, as
in

	y 1993 8 23

; this is used because 'd' is already used for declination.  Since
the date is entered as yyyy mm dd, the y is at least somewhat
mnemonic.  If you enter a date with 'd', the program will catch
it provided that the year is outside the range -90 to +90.

Also, note that the program is 'case sensitive'; for instance,
R will not be recognized as the same as r.

As an example, if you have an object at epoch 2000 coordinates
RA = 19 19 19.0, dec 2 02 02, and you observe it on 1990 October 20
(which is already set when you entered the program) at 21 30 00
local time on the date you have already selected.  You would type

r 19 19 19
d 2 2 2
e 2000
t 21 30 0
=

and the following output is generated:

	W Long (hms): 7 26 28.0, lat (dms): 31 57 12, std time zone   7 hr W

	Local Date and time: Sat, 1990 Oct 20, time  21 30 00.0  MST
	   UT Date and time: Sun, 1990 Oct 21, time  4 30 00.0
	Julian date: 2448185.687500   LMST:  23 00 59.1

	Std epoch--> RA: 19 19 19.0, dec: 2 02 02, ep 2000.00
	Current  --> RA: 19 18 51.1, dec: 2 01 00, ep 1990.80
	HA:  3 42 08; sec.z =    2.006
	altitude  29.90, azimuth 251.89, parallactic angle 53.8

	The sun is down; there is no twilight.
	The moon is down.
	Barycentric corrections: add  -46.5 sec, -27.47 km/sec to
		observed values.

	(Type q if you wish to quit, ? for menu.)

Notice all that has been computed!

The date and time are given in both local and UT.  If daylight
savings time is selected, the post-1986, United States mandated
change dates are used to select whether local time
is reported in DST or Standard.  Note that the label on the local
time will have either an 'S' or a 'D' as the second character,
to indicate standard or daylight.

LMST is the 'local mean sidereal time'; it disagrees with the
hour angle of the equinox by the 'equation of the equinoxes',
which amounts to a couple of seconds at most.

Notice that the object's coordinates are reported both for
the 'standard epoch', which is set with the 'e' option, and for
the mean equinox of date.

The quantity sec z is (for most purposes) nearly the same as the
airmass; the difference grows large only quite near the horizon.
If the object is at a particularly large airmass, or below
the horizon, a comment is printed.  If the object's airmass
is very large, it is not printed to avoid overflowing the space provided.
The altitude is 90 degrees minus the zenith distance; the azimuth
is (as usual) measured north through east.  The parallactic angle
is the position angle (measured N through E at the object)
of the arc that connects the object to the zenith, or loosely
speaking, the position angle of 'straight up'.  This is
useful for setting a spectrograph slit to catch the dispersed
light. (See Filippenko, 1982, PASP, 94, 715 for a discussion;
it is only important if the zenith distance is appreciable, and
its sign change at the meridian masks a continuous change at that
point.)  It is not computed or printed for the southern hemisphere - the
algorithm needs another branch built onto it.

If the moon could be interfering (higher than 2 degrees below the
geometrical horizon), its altitude (not corrected for refraction),
fraction illuminated, approximate RA, dec, altitude, and azimuth are
reported.  Also, the angle subtended at the observer by the object
and the moon is reported.  If the moon is more than two degrees below
the horizon, it is reported to be 'down' and no further information
is printed about it.

If the sun is at a geometric altitude > -18 degr. and  < -0.8 degr,
twilight is reported; if the sun is at geometric altitude
> -0.8 degr, it is reported to be 'up'.  In either of these
cases the RA, dec, altitude, and azimuth of the sun are given.
There are no corrections for refraction.  If the sun is more than
eighteen degrees below the horizon, it is reported to be 'down'.

For instance, changing the date to November 3, 1990 and the time
to 18 hours 30 minutes local time by typing

	y 1990 11 3 t 18 30 0 =

gives the result:

	W Long (hms): 7 26 28.0, lat (dms): 31 57 12, std time zone   7 hr W

	Local Date and time: Sat, 1990 Nov 3, time  18 30 00.0  MST
	   UT Date and time: Sun, 1990 Nov 4, time  1 30 00.0
	Julian date: 2448199.562500   LMST:  20 55 41.3

	Std epoch--> RA: 19 19 19.0, dec: 2 02 02, ep 2000.00
	Current  --> RA: 19 18 51.3, dec: 2 01 00, ep 1990.84
	HA:  1 36 50; sec.z =    1.263
	altitude  52.37, azimuth 222.16, parallactic angle 34.7

	In twilight, sun alt -12.1, az 259.5 ; Sun at  14 35 44, -15 14.5
	Moon (+-0.3deg):  3 39.7,  23 25, alt   3.5, az  64.5; 0.978 illum
	Object is 121.0 degr. from moon.
	Barycentric corrections: add -152.6 sec, -25.85 km/sec
                        to observed values.

	(Type q if you wish to quit, ? for menu.)

CHANGING SITES... s

You can change sites by typing the letter s and answering the prompts.
When you do this, you will be given a menu of single-character
site codes from which to choose.  Your local version
of the program should be customized to offer the most
common choices for your institution.  To choose a site, just
type the letter (be sure to use the correct upper or lower
case) and hit carriage return.  You can also specify
any other site by typing any character NOT on the menu.
If you select one of the 'canned' sites, all the parameters
(latitude, longitude, time zone info, etc.) will be changed to
their standard values for that site.

If you want a site which is not on the menu, you'll have to give
all its parameters.  Otherwise one would risk of changing
the parameters piecemeal and having some parameters which are appropriate
to the site and others which are not.  You'll need to know the
latitude of your site in degrees, minutes, and seconds,
and the WEST longitude in HOURS, minutes, and seconds.
You'll also need the time zone in hours west of Greenwich (e. g.,
Eastern is 5).  You can specify Eastern hemisphere sites by giving
negative numbers for the longitude and time zone, but this has
not been exhaustively checked.

The last parameter prompted for is whether daylight
savings time is to be used in converting between local and UT;
remember that if daylight time is selected, the current (1986+)
prescription mandated for the USA is used to determine whether
daylight time is in effect.

Naturally, you should be sure that you have the correct parameters
for your site.  The outputs from '=' and from the almanac mode
have much of the site information echoed back; you'll probably want to
check it, especially if you've entered it yourself.

MORE GOODIES.

** Greenwich or local input times .. the g command. **

Typing the letter g switches between input in UT and in local time.
The program wakes up assuming that dates and times are input
in local time; typing g makes the program assume that the
input date and time are in UT; a little message is printed
telling you this.  Typing g again switches back to local, and
so on.  Whichever time is assumed for the input is printed
first on output.  Notice that, when you type g, the current
time changes; the input time and date have their same
numerical values, but are now interpreted differently!  Again,
a message is printed to remind you of this.

** Proper motions ... the p command. **

If you type p you will be prompted for annual proper motions of
the object; answer the prompts.  There is one minor complication;
there are (at least!) two conventions in use for the units of the
proper motion in RA.  One is the annual change of the RA itself, generally
given in seconds of time per year; this is used in the SAO Catalog.
The other is the east-west motion in seconds of arc on the sky,
which is the first times 15 cos (delta).  The program prompts
for *each* type; the one you're not using should be entered as
zero.  If you screw up and enter both as nonzero numbers, it will
complain.  Declination proper motions are always entered as
arcsec per annum.

If any of the proper motions are nonzero, the output will display

	-- the original coordinates in the standard epoch and equinox

	-- the coordinates updated for proper motion only (current
	    epoch, *but* standard equinox!)

	-- the coordinates updated for both proper motion and precession
	    (current epoch *and* current equinox).

as well as the proper motions used.  The reason for this is that,
on many modern telescopes, the coordinate readout can be set to a
standard equinox, but the sky of course is always in the present
epoch, regardless of what coordinate set you apply to it.  So,
you want the option of displaying the updated epoch
without changing the equinox.  Note that the proper motions
are not handled rigorously; the current ra is just the
old ra + mu*dt, and similarly for the dec.  This fails very
near the pole or over very long time spans.

** The c command - coordinate conversions. **

Typing c causes the galactic and ecliptic coordinates to be printed.
The galactic coordinates given comply strictly with the IAU definition;
if 1950 coordinates are supplied, the results are essentially perfect.
If 1950 coordinates are not supplied, the coordinates are precessed
to 1950 before being converted to galactic, which leads to slightly
lower accuracy.  The ecliptic coordinates are good to < 0.01 degree,
limited mainly by the crude expression used for the obliquity of the
ecliptic as a function of time.

** The h command - hourly circumstances. **

Typing h lets you create a table of hourly circumstances for the
current site, date, ra, dec, and epoch.
You are prompted for (1) how many hours before (and after)
local midnight to tabulate (e. g., answering 5 will give
you from 19h to 5h local time), and (2) the name of the object
(terminated with a carriage return).  The output looks like:

   *** Hourly airmass for Wholeflaffer 9 - The Next SS433 ***

   Epoch 2000.00: RA  19 19 19.0, dec  2 02 02
   Epoch 1990.80: RA  19 18 51.1, dec  2 01 00

   UT date at local midnight: 1990 Oct 21

     Local      UT      LMST      HA     secz   par.angl.

     19 00     2 00    20 31     1 12    1.212    27.6
     20 00     3 00    21 31     2 12    1.370    42.5
     21 00     4 00    22 31     3 12    1.707    51.1
     22 00     5 00    23 31     4 12    2.482    55.7
     23 00     6 00     0 31     5 12    5.167    57.8
      0 00     7 00     1 31     6 13   (down)    57.9
      1 00     8 00     2 32     7 13   (down)    56.3
      2 00     9 00     3 32     8 13   (down)    52.5
      3 00    10 00     4 32     9 13   (down)    45.7
      4 00    11 00     5 32    10 13   (down)    34.5
      5 00    12 00     6 32    11 13   (down)    17.1


This lets you assess the visibility of the object as a function
of time very easily.  In this case, you'd better have that
crucial observation of Wholeflaffer 9 in the bag before
10 P. M. local time!

One effective way to use this option is to run the program in
background with outuput redirection.  This will create a nice file
of airmass tables for your target objects which one can use
fairly well for a whole observing run.  The details of how to do
this are system-dependent, but the inputs involved might be something like
this, from the beginning of the program to end:

(input)			(comment)

k			(selects Kitt Peak, assuming it's on the site menu).
1990 10 20		(date)
e 2000			(input coordinate epoch)
r 19 19 19		(coordinates .. ra and dec).
d 2 2 2
h 			(hourly circumstances command)
6			(print +- 6 hours from local midnight).
Wholeflaffer 9		(name of object)
r 20 20 20		(for next object)
d 12 12 12
h
6
Flapdoodle's Variable Nebula

(and so on... r, d, h, followed by number of hours to print and name, until..)

q			(exit caclulator mode)
-1			(exit program).

ALGORITHMS, ACCURACY, AND LIMITATIONS.

*Calendar and times. *

Most of the routines use Julian dates, implemented as
double-precision floating point numbers, as their time argument.
If the machine's double-precision mantissa isn't pretty
long, you can run into serious inaccuracy.  Digital's
VAX machines express a JD to about 0.1 sec accuracy, but
this should be checked when the code is ported to another
processer.

The distinctions between UT, Ephemeris Time, Terrestrial Dynamic
Time, and so on, are ignored.

The calendrical routines break down before 1901 and after 2100.
Input outside those dates is rejected and execution terminated.

When printing the phenomena for a given night, the program
assumes implicitly that zone time is at least grossly approximate
to the real local time.  Thus working from a California location
(zone = 8, or Pacific time) and attempting to get times printed
as UT by giving a standard time zone as 0 will give peculiar
behavior.

In most instances, the date and time which are displayed are
computed from the JD.  If the time is very near midnight (within
about 0.1 sec on VAX processors), it is possible to have the
date disagree with the day of the week.  The user is warned
if this is a possibility.

As previously noted, daylight savings time is implemented using
the first-Sunday-in-April to last-Sunday-in-October change
dates mandated by the U. S. Congress in 1986.  There are
minor ambiguities and infelicities just at the time of
the switch - the user is warned if this is possible.

The routine to turn JD into calendar date is adapted from
"Numerical Recipes in c" by Press et al.  The routine to
generate the JD from the date and time was adapted from a
routine originally based on a recipe in the old American
Ephemeris.

* Sun and Moon. *

The moon's position (used also for moonrise and moonset) is computed
using the 'low precision formulae' from the Astronomical Almanac.
These are advertised as having an error which seldom exceeds
0.2 deg in declination and 0.3 deg in RA.  I do not know over
what range of dates this precision can be expected, but it
appears to work well towards the end of the twentieth century.
The topocentric correction (from geocentric to observatory-centered)
is included.  The sun's position is from the Almanac's low-precision
formulae for the sun, which are advertised as good to about 0.001
degrees.

The times of moon- and sunrise and set are computed as the times when
the center of the object is 50 arcminutes below the geometrical
horizon.  This is about the time of contact of the upper limb with
the horizon, once refraction is taken into account.  Variations in
the apparent diameter of the sun and moon are ignored.  The
elevation of the observatory is not taken into account.  Nonetheless,
comparison with the NOAO Newsletter tables generally shows agreement
within +- 1 min for sunrise and sunset, and +- 2 min for
moonrise and moonset, at least at temperate latitudes.  Larger
time errors can be expected at high latitudes, where objects
graze the horizon, since the programs to compute rising, setting,
and twilight iterate until the altitude of the object is within
0.1 degree of the desired altitude.

* Geographical limitations *

The daylight savings time conventions used are local to the U. S.
and to years near the present (1990).

The algorithms used for rising and setting work at tropical
and temperate latitudes, and have been retrofitted to work
at very high latitude as well.  As noted above, rise/set times
are not as accurate at circumpolar latitudes as they are closer
to the equator.  The code has not been tested exhaustively at
very high latitudes, nor has it been tested critically in the
southern or eastern hemispheres, but there are no reasons for
expecting it won't work there.  Problems with computation of
moonrise, etc., which should not arise, are signaled by the message

	 "Looks like we are not converging...".

At very high latitudes, phenomena such as sunrise, twilight, moonrise,
and so on do not always occur.  Thus the almanac program tests
that they should occur before computing the time.  To test,
it uses the declination of the relevant body computed for local
midnight; this can lead to slightly erroneous results, especially
for the moon, which can change declination quickly.  This should
seldom be important.

* Precession *

The precession algorithm is coded directly from L. Taff's very
useful book "Computational Spherical Astronomy" (Wiley).  It uses
a rotation matrix and gives mean positions good to less than
1 arcsec in 50 years.  It works correctly at the poles.
It gives the same answers as the IRAF routine to this accuracy;
also the set of test coordinates given by Smith et al.
(1989, A. J. 97, 265) was reproduced to within 1 arcsec accuracy
(except for proper motions near the poles).  The precession
constants used are the 'old' ones (not the IAU 1976 values); this
makes very little difference expect for the most critical work
(typically << 1 arcsec in 50 years).

Note that this program does not compute the complete apparent place
(including aberration, nutation, refraction, what you had for
breakfast, etc.). If you need this, or if you need to transform
coordinates at greatly sub-arcsecond accuracy (as in transforming
astrometric catalogs onto each other), use a more sophisticated program.

* Local Mean Sidereal Time *

This is generated by a routine from the old Nautical Almanac.  Tests
for the longitude of Greenwich in 1990 give agreement with
the Astronomical Almanac tables to within 0.1 sec.  Also,
the IRAF routine gives the same answers to within 0.1 sec.  Note
that the mean sidereal time is not exactly the hour angle of
the true equinox of date, because of nutation.

* Parallactic Angle *

This quantity - the position angle of a great circle connecting the
object to the zenith - is sometimes used for setting a spectrograph
slit along the angle of atmospheric dispersion.  Its use and importance
are described by Alexei Filippenko (1982, PASP, 94, 715).  Note that
it generally is not important unless you are at least somewhat away
from the zenith - Filippenko tabulates the dispersion.  The angle
is computed and displayed for Northern hemisphere observatories.
The calculation is tricky because of subtleties in the choice
of the root of an inverse trig function.  A careful comparison
with Filippenko's tables over a large range of hour angles and
declinations gave complete agreement.

* Barycentric ('Heliocentric') Corrections *

These are computed from an elliptical earth orbit, with elements
expressed as power series around 1900.  A crude correction to
the solar system barycenter is included, using simple circular
orbits for the four gas giants.  The diurnal rotation is also
included in the velocity calculation but not in the time correction.
The recoil of the earth due to the moon's motion is ignored.  Comparison
with the IRAF routine (claimed good to 0.005 km/s) and painstaking
comparison with the tables of position and velocity of the earth
in the Astronomical Almanac show that the time correction is
generally good to 0.3 sec and the velocity to better than 0.03 km/s.
This should be good enough for all but the most precise work.

* Galactic and Ecliptic Coordinates *

The galactic coordinates conform to the IAU definition and
agree closely with those computed by IRAF.  Roundoff should
be the only source of error for 1950 input coordinates.
The input coordinates are precessed to 1950 before being
transformed to galactic.  The ecliptic coordinates
(referred to the equinox of date) are good to 0.01 degrees; the
source of inaccuracy is the crude expression used for the obliquity
of the ecliptic with time.

** BUGS (and other ungraceful behavior) **

The day and date can disagree within a very close tolerance of
midnight.  This possibility is flagged on output.

The conversion from local to UT is not handled well around
the time when daylight savings time changes to standard
and vice versa.  This possibility is flagged on output.

After a pass through the 'almanac mode', the time is left at
whatever value it had at the end of that process.  It must
be re-specified explicitly using the 't' command.

After you type 'g' to toggle between greenwich and local
time, the time currently in effect changes to the value
which is *numerically* the same in the new system, not the
time which is actually equivalent.  So if you are in the zone
7 hr west (Mountain), and you are using local time, and
the time is 1991 Jul 7, 22 hr 0 mn 0 sec MST; and you type 'g',
the time in force is now 1991 Jul 7, 22 hr 0 mn 0 sec *UT*,
which is 7 hr earlier.  To get the same actual time, you'd have to
enter y 1991 7 8 and t 5 0 0.  The program signals the user
that this is happening.

The twilight and rise/set times are slightly inaccurate at
very high latitudes, since the object comes into the appropriate
altitude at a grazing angle.  Rise/set can be erroneously
reported as not occuring at very high latitudes because the
occurence of rise/set is judged using the position for local
midnight.





	2. A NIGHTTIME ASTRONOMICAL CALENDAR PROGRAM.

This program prints an astronomical calendar for a given year
from a single site.  The algorithms used are for the most part
identical to those used for the circumstances calculator program
described above, but the input and output are different.
The purpose of the calendar is simlilar to that printed annually
in the NOAO newsletter for Kitt Peak; however, the format is
designed to be easier to use, less error-prone, and to give
rather more information than the NOAO calendar.  It can also
be readily used for other observatories.  Again, this is a self-
contained c program which should be easy to run on various computers;
however, the same cautions as listed above apply.

The output has a wide format (about 120 characters).  At the beginning,
some information is printed along with prompts for interactive use
(something which will probably seldom happen.)  Then comes a page
of information about the program and its accuracy, which
is largely redundant with this document.  Next follow the results
for each of the twelve months.

At the very beginning of each month is a formfeed character,
so on many systems, the output can simply be printed on a
line printer with a new page for every month. At the head
of each month is the year and month set off by asterisks.
Also given is the site name, its longitude in HOURS minutes and seconds,
its latitude in DEGREES and decimal minutes, and the standard time
zone.  After some other information, the user is reminded that the
times listed (except for sidereal) are LOCAL times; the name of the
zone is given.  If daylight savings time is used, the user is reminded
of this as well.

The rest of the calendar is organized with one night per line.
Note that this choice is only sensible for nighttime astronomers,
a large (but not all-inclusive) subset.  Though the calendar works
at circumpolar latitudes, this form of organization is not optimal
during the 'midnight sun' either!  A detailed description of the
tabulated quantities follows.

The first column gives the day and date, FOR BOTH EVENING AND MORNING.
This should minimize errors in reading dates.  A blank line
appears between Saturday and Sunday nights.

The next column gives the JD at *local* midnight, severely
rounded off.  The idea is simply to avoid any ambiguity, which
is unfortunately common in tables of JD.  If daylight savings
is in use, the JD is the JD of daylight savings midnight.

The third column gives the Local Mean Sidereal Time at local
midnight; it is (on typical 32-bit machines) rather more accurate
than the nearest-second accuracy which is tabulated.

The next four columns give respectively the times of sunset,
evening twilight, morning twilight, and sunrise.  Thus the columns
are in the same sequence as the actual events, which makes for
easy reading.  The twilight given is 18 degree ('astronomical') twilight,
and the rise/set times given are when the center of the sun
is 50 arcminutes below the horizon; this is roughly the time
when the sun's upper limb touches the horizon, once refraction
and the sun's angular diameter are taken into account.  Accuracy
is as discussed above.  If an event doesn't happen during a night
(e. g., twilight at high latitudes in summer), ellipses ( ... )
are printed in the appropriate column.

The next two columns give a quantity I have found very useful, namely
the sidereal times at evening and morning twilight.  This defines
the range of RA which is accessible on the meridian during the night.

The last five columns pertain to the moon.

The rise and set times are given, provided they
occur within (roughly) a settable number of hours of local midnight.
The idea is to tabulate only the phenomenon that
actually occurs at night.  The table is easier to follow if this number
is set fairly small; 7.5 hours is a good number for 30 degrees
latitude, but the number must be set rather larger for higher latitudes
because the nights can be so long.  Ellipses (...) are printed if
the rise or set does not occur within the specified interval.  Note
that rise and set times, though they occur in successive columns,
do *not* always occur successively in time, depending on the moon's
phase.  Rise/set times are again for 50 arcminutes below the horizon;
variations in the moon's semidiameter are ignored.  The moon ephemerides
are based on the low-precision formulae from the Astronomical
Almanac, which are claimed to seldom give an error greater than
0.3 degrees.  The rise/set times are generally good to better than
2 minutes at temperate latitudes; the same accuracy limits apply
as for the calculator program discussed earlier, since the algorithms
are the same.

The next column gives the fraction of the moon's face which is
illuminated.  New, first quarter, full, and last quarter
correspond approximately to values of 0.00, 0.50, 1.00, and 0.50
respectively for this quantity.  If theta is the angle subtended by
the sun and the moon at the observer, the quantity tabulated is

	0.5 * (1 - cos(theta)).

Finally, the last two columns give the RA and dec of the moon at local
midnight, whether or not the moon is up at that time.  The position
is topocentric, and is again computed from the low-precision
moon formulae.  It is very useful to know the moon's position
if you're having to 'dodge' the moon in the sky.

* Times in the Calendar program. *

Note that the rise, set, and twilight times given in the calendar
are for THE LOCAL TIME ZONE.  (The sidereal times are of course
strictly local and have nothing to do with the time zone.)  If
you wish, daylight savings times can be listed; if you use
this feature, all local times listed will be daylight savings time
from the first Sunday in April to the last in October.  The
switchover occurs at 2 AM on Sunday morning.  This can in principle
lead to an ambiguity around the time of time change (in the fall,
it's 1:30 AM local time twice on the same night!), but you should
be able to unravel this rare case from continuity with the
preceding and following nights.  Note that the convention used
for the dates of time change has been in use in the U.S. since
around 1986; to handle other locations, or earlier times, the source
code must be changed.  The code doesn't allow you to select daylight
savings time in the southern hemisphere - the change dates coded into
the program make no sense in the south.  One can always use purely
standard times if the change dates present a problem, or you
can recode the relevant routine in the source code (called
find_dst_bounds).

The header that appears on each page makes a note if daylight savings
time is used.

RUNNING THE CALENDAR.

You will probably never want to actually run the calendar interactively;
it takes a while to run, and it produces an output wider than
most terminals.  To run it, you'll want to use a background job, with
output redirected to a file you can print on some wide device
(e. g., a laserwriter in landscape mode).

I describe below the input that the program will call for when run
non-interactively.  However, the program is also designed so that you
can 'test-run' it interactively to reconnoiter the inputs it will
require and the options available.  The program first asks you
to select a site, and prints a menu of 'canned' possibilities.
You can select one of the 'canned' sites, or enter all the parameters
for another site.  The last input prompted for is the year for which
to print the calendar; giving a negative year here exits the program.

Before producing the calendar, then, your first step should be
to run the program interactively, mostly to be sure which
'canned sites' are available in your own version of the program.
After that, you create a little procedure or job, with the
output redirected into a file, to make the calendar itself.
The exact format of this job will be dependent on your system, and
on just what you want to do.  However, the inputs you need will
be system-independent.  Here are some annotated examples; the
text to the right is commentary, not to be repeated put in
the job itself.

Example 1 - for one of the 'canned sites.'.

k		(code for kitt peak, assumed to be one of the 'canned sites')
1991		(year for which calendar is to be run)
1 12		(print all months)

Example 2 - for another site.

a			(another site - not one of the canned ones).
6 15 28			(WEST longitude, HOURS MINUTES SECONDS.)
44 44 44		(latitude, DEGREES MINUTES SECONDS).
6			(standard time zone, hours WEST of Greenwich)
USND Hoople		(Site name; terminate with carriage return).
Central			(Time zone name, terminated with carriage return).
8			(Hours before/after midnight to tabulate moonrise/set).
1			(do use daylight savings time).
1991			(year)
1 12			(months)


Naturally, you should be especially careful about your site parameters;
anyone entering a new site in the source code should be downright
compulsive, since lots of people may depend on the accuracy.  The user
should check the  output to be sure the parameters repeated are correct;
the latitude, longitude, etc. are printed at the top of every month's page.


** Examples of how to run the program in background for
    UNIX and VMS systems **.

This is not of complete generality, but covers the bases for most
users.

On a UNIX system, if you've named your executable task 'skycalendar',
you'd edit a file called 'inputs' containing the input data,
just as above.  Then type

skycalendar < inputs > hoople_1991 &

which could be paraphrased as 'run the calendar program, taking
input from (<) the file named infile, directing output to (>) a
file named hoople_1991, and do it in background (&)'.

The user prompts are printed to the standard error stream so one can
run the calendar program with just the standard output redirected to
capture the calendar output and still be prompted and enter responses
interactively.  For example

skycalendard >hoople_1991
[Interactive prompts]

On a VMS system, you would edit a command file - let's call
it CALDRIVE.COM - which would have the first line

$ run skycalendar

with subsequent input on successive lines without dollar signs at the
front (again, just as above).  Then you'd type

@CALDRIVE/OUT=HOOPLE_1991.LIS

to run the command file and direct the outfile to a file called
HOOPLE_1991.LIS.



** Sample Output from the Calendar Program **

The following output came directly from a run of the program using
the input quantities given in the example above.  It should be used
to check the results in a new site.

Because the output is so wide, I've added carriage returns; in the
main body of the calendar, they are consistently right after the
columns relating to the sun.  This has a terrible effect on legibility,
but fits it on the page...

                                       ****** 1991 Jan ******

Univ. South. North Dakota at Hoople:   6 16 56 (hms) West,
  44 44.7 (dms) North, Standard time zone  6 hr.West
Each line gives phenomena for one night.  Moon illum and coords
  computed for local midnight.
Note that times given are Central.   DAYLIGHT SAVINGS used,
  1st Sun in April -> last in Oct.

  Date (eve/morn)      JDmid    LMSTmidn   ---------- Sun: ---------
   LST twilight:   ------------- Moon: -----------
  (1991 at start)    (-2440000)            set  twi.end twi.beg rise
    eve    morn   rise    set   %illum   RA      Dec

Tue Jan 01/Wed Jan 02  8258.8    6 28 34   16 47  18 33   6 09  7 54
    1 00  12 38   18 08  .....   0.97   8 17.4  19 00
Wed Jan 02/Thu Jan 03  8259.8    6 32 31   16 48  18 33   6 09  7 54
    1 05  12 42   19 29  .....   0.91   9 15.3  13 52
Thu Jan 03/Fri Jan 04  8260.8    6 36 28   16 49  18 34   6 09  7 54
    1 10  12 46   20 46  .....   0.83  10 08.7   8 05
Fri Jan 04/Sat Jan 05  8261.8    6 40 24   16 50  18 35   6 09  7 54
    1 15  12 50   22 00  .....   0.74  10 58.7   2 04
Sat Jan 05/Sun Jan 06  8262.8    6 44 21   16 51  18 36   6 09  7 54
    1 19  12 54   23 10  .....   0.65  11 46.3 - 3 50


3. CAUTIONS APPLYING TO BOTH PROGRAMS.

When these codes are ported to a new system, the results should
be checked carefully for accuracy.  The sample output
in this document should be reproduced correctly.  The user
assumes responsibility for the correct operation of the
programs and the sensible interpretation of their results.
The user's attention is drawn to the known limitations
of the algorithms documented above.

  While the programs have been tested carefully, with
the results given above, the author makes no guarantee that this
level of accuracy will obtain in all circumstances on all machines.
I explicitly disavow any responsibility, express or implied, for
damages resulting from use of the program.  Output from
this program should never be used as evidence in a court of law,
or to make decisions which might cause bodily harm if the
results weren't right.

  Nonetheless, I think they work very well and are really handy for
the practicing astronomer!

** Maintainance **

  If you find a real problem, not due to your local machine and
not documented above, write

	John Thorstensen
	Dept. of Physics and Astronomy
	Dartmouth College
	Hanover, NH 03755

	John.Thorstensen@dartmouth.edu