• Displaying the airmass graph causes a little grey object-selector menu to appear, which shows the the object list if you've loaded one. Use this to select which objects to plot on the airmass graph. To select more than one object at a time, use ctrl-click, that is, hold down the Ctrl key and click on the name with the left mouse button. Then click on the Plot Airmasses button to see nice color-coded curves for the different objects.
• Within the airmass graph window itself, a mouse click sets the program time to the time you clicked, and updates everything (it's pretty dramatic). This lets you quickly see the circumstances at any point during the night.

The output parameters on the right-hand side of the window are:

• sidereal -- the local mean sidereal time, in H M S.
• HA -- the hour angle, in H M S. Negative values are east. The field turns orange when the HA is more than 6 hours.
• Airmass -- the true airmass, which is slightly different from the secant of z. Yellow, orange, and red warning colors are used at large airmass; yellow starts at airmass 2, orange at 3, and red at 4 (which is a huge airmass).
• parallactic -- the position angle of "straight up", and its 180-degree opposite.
• SunRAdec -- the topocentric (corrected for observer's horizontal parallax) position of the sun, in the equinox of date. Accuracy should be better than 1 arcsec.
• SunAltAz -- the altitude and azimuth of the sun, uncorrected for refraction.
• ZTwilight -- An estimate of how many magnitudes of twilight there is in blue light at the zenith. Yellow, orange, and red draw attention to this field when twilight might be an issue. Light blue indicates daytime sky.
• MoonPhase -- A verbal description of the moon phase.
• moonRAdec -- The topocentric position of the moon in the equinox of date. The moon's horizontal parallax can be very large (up to 1 degree), so the correction is important here. The lunar ephemeris used is good to about 10 arcseconds.
• moonAltAz -- Altitude and azimuth of the moon, uncorrected for refraction.
• illumFrac -- Fraction of the moon's face that is illuminated.
• LunSkyBright -- an estimate of the brightness of scattered moonlight, in V magnitudes per square arcsecond, at the coordinates you're looking at. This is based on K. Krisciunas and B. Schaefer's analytical fit to their empirical measurements (1991, PASP, 103, 1033). An elaborate warning color scheme is used, starting with light blue when the background is roughly doubled from its dark value, and turning a light purple to indicate "normal" bright-run conditions. When you're close to the moon a yellow-orange-red scheme comes into play.
• Moon-Obj ang. -- Angle between the moon and the object. Warning colors are used to indicate problematic conditions.
• Bary. JD -- The time corrected to the solar system center-of-mass (nearly the same as the heliocentric correction, but more correct), and the size of the correction, which is accurate to a couple of hundredths of a second.
• Bary. Vcorrn -- Add this to an observed radial velocity to get the value observed from the solar system barycenter. Accuracy is much better than 10 m/s.
• Constellation -- The constellation that the current coordinates lie in. This is computed using the algorithm given by N. G. Roman (1987, PASP, 99, 695). Francois Ochsenbein's (CDS Strasbourg) implementation of this algorithm in C is ported here to Java.
• Planet Warning? -- This field lights up when your coordinates are near to a planet. Being close to a bright planet (e.g. 1 degree from Jupiter) gets a red warning.

Except for the Site Menu and Sky Display window, these other windows are all hidden on startup. You can get the windows to show using the buttons at the bottom of the main panel -- the buttons toggle the corresponding window on and off. Most of the windows also have their own "hide" buttons. Don't use your windowing system's buttons to close windows, as this can kill processes.

The Hourly Circumstances window is a popular favorite. It gives the circumstances for the object coordinates (from the main window), computed for each hour through the night. Time is given in Local, UT, and sidereal (LST), followed by the hour angle and airmass, followed by the altitude of the moon and the sun. Warning colors (red, orange, yellow, light purple, and blue) are used in the HA, airmass, moonalt, and sunalt columns. If the time in the main window is before noon, the previous night is shown; if the time is after noon, the coming night is shown. This is so that if you run a calculation with the time set to 2 AM, it computes the table for the most appropriate night.

The refresh time for this window can be noticeable; if you're not using the output, you can hide it using the button provided, which turns off the refresh and can speed things up a bit. You can put the window back up using the button in the main window.

A button is provided to dump the contents of this window to a file in your local directory. The output is appended to the file, so you can run a number of objects and then print the file.

The Nightly Almanac window gives times of sunset, sunrise, twilight (when the sun is 18 degrees below the horizon), moonrise, and moonset, defined as when the upper limb is on the visible horizon. When the terrain elevation is zero (this quantity is defined here as the elevation of the observatory above the terrain that forms its horizon), the rise and set times are computed for when the center of the sun or moon is 90 degrees, 50 minutes from the zenith, which accounts roughly for atmospheric refraction and the angular size. If the terrain elevation is greater than zero, the rise and set times are adjusted accordingly. The sidereal times at evening and morning 18-degree twilight are also listed.

If the time in the main program is before local noon, the previous night is computed. If it's after local noon, the next night is computed. This is just like the Hourly Circumstances window. The window is invisible on startup, but can be revealed or hidden using the buttons provided.

The Planet Table gives low-precision coordinates of the planets, derived from algorithms given by Jean Meeus in Astronomical Formulae for Calculators (Willman-Bell). The inner planets are good to about a minute of arc, but the outer planets are somewhat worse, and Pluto (I know, it's not a planet any more officially) is pretty bad. Coordinates are in the epoch of date. (These planetary positions are also used internally to find the offset between the heliocenter and the barycenter for the barycentric corrections.) The last column in the table, Proximity, gives the angular distance between the planet and the coordinates that are used in the main window. The planet table can be printed using the built-in print method provided by Java for this class.

The Object List window lets you read in a list of astronomical objects. Reading in a list of objects read in greatly enhances the usability and power of the program -- you don't have to type in coordinates, and the objects are graphed on the Sky Display. The list must be in this format:

     name_no_blanks   hh mm ss   dd mm ss   equinox  [optional web address]

     4U1234+56   12 34 35.3  56 01 02   1950   file:///home/thorstensen/charts/4u1234.jpg

You'll notice that once you've loaded a list, its name appears in a second little selector box in the window. This makes it easy to recall the contents of the list without the tedium of going through the file-selection popup. So, you can have several different lists, say for different categories of objects or different programs, and quickly swap between them. Just click on Clear List to get rid of the old objects, select the previously loaded list in the box, and presto, you've switched lists. Beware that strange behavior may result if you have two lists loaded at once, and they have objects in common.

What's with that web address? If, when the list is loaded, there is an extra field with either "file" or "http" in it, this extra field will be loaded as a web address associated with the object. Note tha this can be a file on your own system as in the example above. If you select this object, it's web address appears at the bottom of the main window; pressing the Send button will send this to your desktop for appropriate action, such as loading to a browser, or popping an image file in a viewer, or opening the file in a PDF reader. This lets you link in whatever other information about the object you'd like to have available quickly -- a finding chart, notes on how to observe it, notes on the science you're trying to accomplish or the observing conditions -- whatever!

The Alternate Coordinates window gives the coordinates precessed to the equinox of date, the galactic coordinates, (which are rigorously accurate), and ecliptic coordinates. There's no hide button -- use the button on the main window to toggle the window on and off.

The white background behind the galactic coordinates signifies that they can be used for input. Entering a value in the galactic latitude or longitude fields and pressing Enter sets the coordinates in the main window to the location specified by the longitude and latitude you entered. Thus the program can serve as a galactic-to-equatorial converter. I have not implemented an analagous function for ecliptic coordinates.

The Seasonal Observability window is useful for planning when to observe an object (for example, in filling out a time request form). It takes the date from the main window, figures out when new and full moons will occur for about three months on either side, and generates a table, each line of which gives a brief summary of the object's observability at each of these dates. The hour angle and airmass are given at the start of the night, the natural center of the night, and the end of the night. The last three columns give the number of hours that the object is accessible without twilight and at airmasses of less than 3, less than 2, and less than 1.5. A button is provided to print the output.

The Parallactic... window is a tool that computes where to set an instrument rotator for an upcoming observation. Because air is dispersive (i.e., its index of refraction varies with wavelength), an object observed away from the zenith will be smeared into a small spectrum, with the violet end closer to the zenith than the red end. If you're using a long-slit spectrograph, you can capture the whole spectrum by aligning the slit with the parallactic angle, which is the angle between (a) a great circle arc toward the pole, and (b) a great circle arc toward the zenith, measured north through east. The parallactic angle is, crudely, the "position angle of straight up". The tool provided here computes the refraction-weighted average parallactic angle -- which is the optimal angle for the slit -- for your target for a specified upcoming time interval. To use it,

• Enter the time interval until the observation starts, measured from the time depicted in the main window. The default unit is minutes, but you can also specify (for example) '180 s' or '2 h'.
• Enter the dwell time, i.e., how long you intend to stay on this target.
• To refresh the display, press Compute or simply hit Enter in any of the input fields.

Note that for any given instrumental setup, the rotator setting may not correspond directly to the projected position angle of the slit. This is not an issue with the MDM 2.4m with default north-south slits -- the slit angle is simply the same as the rotator.

The graph shows the Cross-slit refraction factor as a function of time during the anticipated exposure, for the optimal angle (in white) and some other rotations of the instrument. The quantity graphed is

Cross slit factor =  tan[zenith distance] * sin[rotator angle - optimal angle].

The magenta and cyan curves that flank the optimal white curve show results for angles at 15-degree intervals away from optimal. This shows how critical the rotation setting is (near the zenith, it doesn't matter, but it matters a lot at high airmass). In addition, the red curve shows the result for the rotator setting you specify in the Current Rotator box. This is handy if you're already set up at some angle and want to see if you can get away with not rotating the instrument for the next target.

How stringent do you need to be? That depends on a host of factors; how big your slit is, your spectral range (refraction is almost constant across a narrow wavelength range), the seeing, your scientific goals, and so on. Alex Filippenko ( 1982PASP...94..715F ) has a complete discussion. For a 1-arcsecond slit with a wide passband (4000-7500 Angstroms), a good rule might be to keep the factor less than 1.

The parallactic window background is black at night and fades into blue during twilight; this should alert you if a planned exposure will extend into twilight (note that astronomical twilight is defined very stringently, so that some twilight is usually tolerable). In addition, the airmass at the start and end of the specified interval is displayed, using the same warning color scheme as in the main window.

The Sky Display button in the main window toggles the display on and off (it does take a lot of screen real estate). The window plots a map of the sky, showing stars to V = 4.5, the sun, moon, and the planets (including Pluto, whatever you want to call it). If you have an object list loaded, it also plots each object as a text string, the bottom of which is centered on the object. The coordinates in the main program are marked with a greenish box. The stars are generally not plotted in a pure white, but with a color derived from the spectral type; the RGB values chosen to represent the spectral types are based on those computed by M. N. Charity (see http://www.vendian.org/mncharity/dir3/starcolor/). I de-saturated his suggested colors slightly (moved them toward white) because the full colors were a bit distracting.

Red arcs indicate the meridian, the equator, and lines of constant hour angle every 2 h out to +- 6 h. Dotted red circles indicate 2, 3, and 4 airmasses.

The moon is drawn at exaggerated size but in the correct phase and orientation. The planets are sized according to magnitude, with the fainter ones rendered as very small dots. A clock drawn in the upper right corner shows the prevailing local time; the Site and Universal Time information are printed at the lower right. The background color is controlled by where the sun is -- when there is no twilight the background is black (even if the moon is bright). There's a small, discontinous jump to dark grey at the beginning and end of twilight, and a continuous ramp between twilight and daylight, which is rendered in blue. This proves very helpful in keeping the user oriented in time.

The sky display updates whenever the main window changes, so the Auto Step command results in a somewhat jerky animation.

The sky display recognizes several mouse and keyboard commands , as follows. But first, note that the window will not respond to the keyboard commands unless it has focus (with most systems, this is indicated by some kind of change in the window border). The mouse commands work regardless (though I have heard of people having issues with these features on Macs running OS-X).

• Pressing and holding the Right Mouse Button pops up a little command summary.
• Middle Mouse Button (or typing 'c' at the keyboard) sets the position in the main program to the position of the mouse. (The object name resets to 'null'.)
• Left Mouse Button , or 's', looks for the listed object nearest the mouse, and sets the main window to that object. You need to hit it within about 5 degrees.
• 'w' - select the nearest object and send its web address.
• 'f' - step the time forward (same as "Step Forward") in the main window.
• 'b' - step the time back (same as "Step Back") in the main window.
• 'n' - set the time to Now (same as "Set to Now" in the main window).
• 'z' - Zoom in by a factor of two around the mouse position.
• 'o' - zoom Out by a factor of two around the mouse position.
• 'p' - Pan, or recenter at the mouse position.
• 'r' - Restore the original view.
• 'h' - set the coordinates and object name to that of the bright (HR catalog) star closest to the cursor.

This is surely an incomplete list:

• Do not use trust this program for archeoastronomy. It is designed for use near the present time and the calendrical, lunar, precession, and planetary calculations will surely be flaky outside of a couple centuries from the present time. It should work well within that range.
• This program is not designed as a teaching tool. While it can certainly be used to supplement instruction, it isn't meant to be a standalone tutorial. Users are expected to understand the relevant concepts.
• The code has not been extensively tested at high geographic latitudes.
• The planetary ephemeris used is not particularly accurate -- it is meant to be small, portable, reasonably fast, and "good enough". If you need to aim directly at a planet, or calculate stellar occultations, use something else, e.g. get your positions from the JPL Horizons site.
• The sky display is not a full-featured planetarium program, like Elwood Downey's excellent XEphem (for unix/linux) or Bill Gray's Guide program (for Windows), or any of the many other commercially available programs. It is meant as a tool for planning and carrying out observations.
• The source code is messy. I've written a lot of code in my life but I am a novice with Java, so the souce code has many shortcomings and aesthetic flaws (e.g., no consistent capitalization style). It is distributed as one giant file, which is not the usual practice. However, it does run!

This program is a re-implementation in Java of the venerable skycalc code, which is a text-only program written entirely in C. Around 2005 I wrote a graphical user interface for skycalc by wrapping the C routines in Python and implementing the user interface with Python's Tkinter module, and I wrote a sky display similar to the one used here. This proved extremely useful, but the software dependencies complicate installation, so I re-wrote the software in Java. Much of the "guts" are taken line-by-line from earlier versions, but the object orientation in the Java code is designed more logically than in the python versions.

Accuracy. A rough extrapolation of delta-T is used for the time argument of the lunar and solar calculations. The sun should be good to 1 arcsecond or so, the moon to a few arcseconds. Comparison with the JPL ephemerides shows that the barycentric corrections are good to a few meters per second in velocity and a few hundredths of a second in time. The precession routine used conforms to the IAU 1976 resolutions, and is not as rigorous as the 2000 conventions; the penalty in accuracy is of order 0.1 arcsecond. As noted above, the planetary ephemerides are only accurate enough for rough purposes. The text-based Skycalc program has an extensive manual describing the algorithms used; the present Java code uses the same algorithms (and gives identical results as far as I have been able to test).

Legalities. I am offering this program freely but claim copyright. Anyone may copy and modify the code, provided that the credit banner with my name and institutional affiliation is not altered. Although I have been careful to ensure that the code is correct, I make no claim that it will always be correct or sufficiently accurate. I also make no claim that it will be suitable for your application. This code should never be relied for applications in which personal safety might be an issue, and it should not be considered authoritative for legal purposes.

I will not be able to answer all queries, but if you believe there is a bug, or have a suggestion for an improvement, or just want to comment, please do email me (john dot thorstensen at dartmouth dot edu).