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