|A short guide to skycalcgui and skycalcdisp.py|
|John Thorstensen, Department of Physics and Astronomy, Dartmouth College|
The programs skycalcgui.py and skycalcdisp.py perform "time-and-the-sky" calculations of interest to astronomers carrying out nighttime observations. Both versions use graphical user interfaces (GUIs), which gives them a look-and-feel similar to web forms. They are based on the venerable skycalc program, which has a text-based interface. (The software distribution also contains the most recent version of the text-based program; installation of this is optional).
The gui and disp versions differ only in that the latter has a "planetarium display" option which plots a map of the visible sky. This can be enormously helpful. but is more difficult to install because its software dependencies.
While the graphical user interface should make the program fairly intuitive, this guide may point out some less obvious features. It may also be useful for those who are deciding whether or not to install it.
The GUI is written in Python and uses Python's Tkinter module. You can see if these are available on your system by typing
python from Tkinter import *... if there aren't any error messages, you should be fine.
If they don't come up, you might try installing the STScI-Python bundle from the Pyraf, website. Once you have Pyraf running, the rest is easy (except for the ppgplot stuff described below, which is separate). While you're at it, grab numarray (see below). Nearly all IRAF users will find Pyraf to be very useful, especially its scripting capabilities. It will change your life!
The planetarium display in skycalcdisp.py is built on Tim Pearson's PGPLOT graphics subroutine library, and also on a Python wrapper for PGPLOT written by Nick Patavalis, which is called ppgplot. The ppgplot wrapper requires that all array arguments be the special "array" type used by the numarray package. This package is available from Space Telescope Science Institute. Note that ppgplot can also be built to use Numeric (the precursor to numarray), but the two versions are mutually incompatible. The ppgplot and numarray packages are useful for many purposes beyond skycalcdisp, so they may be worth installing in any case. Again, note that numarray can easily be installed as part of Pyraf.
There is an older, text-based version called skycalc which offers similar functionality to the GUI-based programs. It is easy to use and simpler to install, since it requires only the C compiler and standard libraries to build. Although skycalc is easy to learn, the GUI will be more intuitive to most users.
See the README file in the source directory for instructions as to how to install these programs. A makefile is provided for the text-based versions, and a setup.py for the python-based versions. These should greatly simplify the task of installation.
One note on the display version -- if the planetarium display fails with a runtime error about something being "not an array", this is a symptom that ppgplot is not configured for the right numerical python version. If you have Numeric installed, try changing the line early in the source code which reads "from numarray import *" to "from Numeric import *". This may fix it.
To make the computations go,
For more information, look through the help text or reference manual, which pop up if you push their buttons. If you have questions about the details of the calculations or their expected accuracy, refer to the extensive manual for the (text-based) skycalc program. The underlying C-language functions used in skycalc are largely the same as for the GUI versions. The "doc" directory of the present distribution contains versions of the skycalc manual in several different formats.
Most of the buttons in the panel at the bottom of the window spawn subwindows. For some (but not all) of these, clicking on their buttons in the main window will put them in the foreground if they have been buried by other windows. The Planetarium, Text Tables, and Object List windows are exceptions to this rule - the planetarium's button toggles it on and off; the Text Tables and Get object list buttons spawn new instances of the windows.
The Hourly Airmass window tends to be heavily used. It provides an hour-by-hour report of the most important circumstances through the night. The circumstances are computed for the celestial location, geographic site, and date set in the main window. If the input time in the main window is before local noon, the previous night is presented (so if it's past midnight you still get the current night); if the time is after noon, the data are for that night.
The first columns give the time in three forms: local clock time (daylight savings if it is in effect), UT, and sidereal. Then come the hour angle, airmass, and the altitudes of the moon (if above the horizon) and the sun (if it is higher than 18 degrees below the horizon). The display typically goes from a little before sunset to a little after sunrise, though this can vary somewhat. There are enough lines to cover the longest nights adequately for latitudes less than about 50 degrees.
Colors are used to warn the user of potentially difficult conditions, as follows:
Pushing one of the site buttons loads the parameters for the listed site and refreshes the calculations.
If your site is not on the menu, you'll have to enter the parameters one-by-one in the main window. BUT NOTE: before you do this, you need to select the last choice, Other (allow user entries). If you don't, your painstakingly-entered numbers will be WIPED OUT when you refresh the output! This happens because the program reads the menu choice from this window and resets the site parameters whenever a computation is done.
If you do need to load your own site by hand, note that you can enter longitude in degrees east (the almanac convention) by appending " d e" to the longitude. The value will reappear as hours, minutes, and seconds west, which is the program's internal convention.
Entering sites by hand gets old real fast, so you may want to customize the source code to include your favorite site. Just look at cooclasses.py and follow the examples given there.
If you push Get object list in the main window, a file-selection dialog box appears, and once you've selected a properly-formatted object list file, a window similar to the one above appears. The expected object file format is one object per line, given as
name rah ram ras decd decm decs equinoxor for example,
4U2129+47 21 29 36.2 47 04 08 1950.You can't have any blank space in the name, and you need three numbers for each coordinate separated by blank space. All the information has to be there (no defaults). Otherwise the format is free -- the numbers can be in any column. If you have a negative dec, the minus sign must be flush with the degrees, as in
PiStar 3 14 15.9 -0 03 14 2000(-0 evaluates correctly as a negative number).
Once you've loaded a list, double-clicking a selection in this box loads its coordinates in the program and refreshes all the output. This makes it easy to check a list of targets for observability by running through your list and looking at the Hourly Airmass window. The object list figures in several use scenarios described later.
Using the buttons provided, you can sort the list in various obvious ways. List by proximity is the least obvious -- this sorts in order of proximity to the currently-set coordinates. The dismiss list button removes the objects from the list and destroys the window. You can have multiple lists open at the same time -- each press of the Get object list button on the main window creates a new list window. Dismissing a list removes only the objects associated with that list. If you load a new list which has an object which is already loaded (i.e., you create a name collision), the object is loaded with "|" appended and prepended to the name.
This window does computations which produce tables of data. It holds up to 500 lines of output. The object and site coordinates are taken from the main window; additional input parameters are set with the input boxes provided. There are three different calculations available:
The max sunalt and max airmass numbers are used to filter the output from "Compute Times" and "Compute phases" calculations, for example to those events visible during darkness from your site. At the end of twilight, the altitude of the sun is -18 (the units are degrees). To turn off filtering, set the max sunalt to +90 and the max airmass to -1.
The Erase output button clears the output window, and the Dump output button writes the contents of the window to a text file "skycalc.out".
The text tool used in the window is actually a primitive text editor. If you like, you can annotate your output before you write it to a file.
The Nightly Almanac window lists the times of various phenomena through the night. If the input time from the main window is before noon, the previous night is listed.
Rise and set times are adjusted for the depression of the horizon using the "elevhoriz" site parameter from the main window. Refraction is taken into account and the rise- and set time refers to the upper limb of the object. Actual times will vary by around a minute because of refraction, and much more in sites with irregular horizons.
Moonrise and moonset are listed in the order they occur. One or the other may not be listed if it occurs around mid-day. You can expect bizarre behavior for sites at very high latitudes.
Several rather arcane items appear on the Alternate Coordinates window. At the top are the coordinates at the date specified in the main window, corrected for precession and proper motion (if any). There are a few input variables in this window - they're here since most people won't need to use them much. They are:
The two components of proper motion can be entered on the indicated line, and the radiobuttons control how the proper motion will be interpreted (more below). The units of proper motion are milliarcsec per year (not arcsec!) for the magnitude, and degrees for the position angle (in the third choice).
If the first radiobutton is checked, the first number in the PM pair is interpreted as the number of milliarcsec per year the object would move east on an image; if the second button is pushed, the first number is how many milliarcsec per year the right ascension increases. These are the same at the equator, but away from the equator, the second option requires a larger number to describe the same easterly motion. Note that the second convention is used by the UCAC2. If the third radiobutton is checked, the proper motion pair is interpreted as a magnitude in milliarcsec per year and a position angle in degrees (0 = moving due north, 90 = due east, and so on).
The "epoch" line requires careful explanation, since the distinction between epoch and equinox is often not appreciated.
The epoch field here is the epoch of the position quoted in the main window, and only makes a difference if there is a non-zero proper motion. (The equinox of the input coordinates is set in the main window).
Note that the coordinates listed just below the epoch are for the coordinates at the time of the input date specified in the main window, but are referred to the input equinox -- that is, they are corrected for proper motion only, but not precessed.
Ecliptic and galactic coordinates are given toward the bottom. The galactic coordinates accurately conform to the IAU definition.
Since the figure was prepared, one more output variable has been added - the parallax factors, which are the parallax displacements in RA and dec for a star at unit distance, that is, the displacements in arcsec for a star at 1 pc - there are no stars that close, of course.
One note: The precession constants used are the ones recommended by the IAU in 1976. The IAU has since recommended improved precession algorithms. These are not yet implemented here, but for most optical-astronomy purposes the differences will not be a concern.
The planets window gives low-precision coordinates of the planets, and their hour angle at the date and time specified in the main window. The last column gives the separation in the sky between the input coordinates and the planet. When this dips below 1 degree for any planet, the line for that planet turns orange. An orange warning appears in the lower right of the main window, too, together with the name of the possibly troublesome planet(s).
I've saved the best for last!
If you can get ppgplot going, you can run skycaldisp.py, which is identical to skycalgui.py except for the addition of this planetarium display.
One useful strategy is to jump the time forward (or back) by typing the left and right arrow keys in the main window. By varying the timestep, one can visualize hourly and daily circumstances (e.g, watching the moon move night by night through the various targets one has loaded).
As noted earlier, this display requires that ppgplot be loaded, which in turn requires installation of PGPLOT and its C-bindings. This takes some doing, but is not particularly difficult on recent Linux systems. See the README included with the software distribution for some hints on environment variables which may be needed to run ppgplot. I've run into difficulties on Mac OS-X, probably because I'm unfamiliar with the architecture. I'd welcome details of successful Mac OS-X ports.
When a program gets this complicated, it can be helpful to illustrate its use in some common situations.
I'm applying for observing time at Tololo. What should I put for "Range of Acceptable Dates"? Also, I need dark sky; how far from new moon I can stand?
After a little playing around, you'll have a good idea of the range of dates, and how far from new moon you can accept. Of course, the lunar sky brightness values are not firm predictions -- haze, thin cloud, volcanic aerosols, or whatever can greatly increase the sky brightness.
It's getting near twilight; I'm in the middle of an exposure and realize that I'd like to grab a short exposure of another target, but twilight and airmass may be a problem. I can be on target in about 25 minutes. What will the situation be then?
I'm going observing next week. I have a lot of potential targets, and am wondering which ones I might be able to get.
If you have the planetarium display these scenarios can all be made more vivid and intuitive. This takes up a lot of screen real estate and requires a fast machine (e.g. recent PC) to redraw the display with acceptable speed. Note that the planetarium display toggles on and off when you press its button on the main window.
Here is a scenario in which the planetarium display is especially helpful:
I have two dozen targets of varying difficulty and importance, a waxing moon, and only one night of observing time left. I won't be able to get to all of them. How can I visualize the situation through the night and decide which ones to go for?