Using JSkyCalc13mGS
John Thorstensen, Dartmouth College; 2014 December

Left: The main control window for JSkyCalc13mGS. This is similar to the JSkyCalc main window, with a few extras. Right: The JSkyCalc13mGS sky display window. A list of objects has been loaded. The telescope is pointing at the red circle - it is in the zenith at the moment. The blue square shows the coordinates that have been loaded in the main window, in this case the coordinates of a standard star. The shade of blue used for the background darkens as twilight deepens, and goes to black at night. The orange arc near the pole traces the hour angle limit set by interference with the telescope's north pier.

The telescope control panel GUI. You need this to control the dome and the mirror cover, turn tracking on and off, and so on.

Important Background -- What this is and What this isn't:

This is a special version of JSkyCalc, retrofitted for pointing the 1.3m telescope at MDM and selecting guide stars. It does not control the mirror cover, dome, and so on.

JSkyCalc13mGS therefore supplements the control panel GUI (shown above along with two of the JSkyCalc windows), but does not replace it. You will need to run the control panel GUI as well as JSkyCalc13m.

Both the control panel GUI and JSkyCalc13mGS work internally by talking to Dick Treffers' telescope control program over a socket, which is a little like a telephone connection between independent computer programs. Because Dick's program sits and listens for requests, it is known as a server, whereas both the TCS GUI and JSkyCalc13m are called clients. It's important to understand these points:

It's not a good idea to move the telescope with both programs at the same time. It shouldn't cause any catastrophes, but it may produce weird behavior. You might be tempted to try this if the telescope doesn't start moving the moment you tell it to. Be patient -- remember that the telescope server program can only do one thing at a time. If there's a delay, the server may just be busy.

Here's what JSkyCalc13mGS gives you:

Using JSkyCalc13mGS at the Telescope

(Note: farther down there is a complete manual on the standard JSkyCalc.)

Starting. The program ordinarily runs on the workstation mdm13ws1 (it's available on any of the similarly-named servers. To start it, simply pull down the Applications menu and look under Telescope Control. Interally, this executes the command /usr/bin/java -cp /lhome/obspkg/thorTools/JSkyCalc13mGS JSkyCalc13mGS, which you can type from a terminal if the menu fails for some reason.

As noted earlier, JSkyCalc13mGS will refuse to start unless Dick Treffers' telescope control server is running, because Dick's program actually runs the telescope. When JSkyCalc13m starts up, it immediately tries to connect to the telescope control server; if it can't for any reason, it puts up a dialog box that lets you fix the problem:

The object-selector window. The lower panels let you keep several different target lists ready to go without having to reload them every time.

Handling object lists. One main point of the program is to handle object lists, so you don't have to type in coordinates every time you set the telescope. An object list is a file with coordinates in it, with one object per line, in this format:

     name_no_blanks   hh mm ss   dd mm ss   equinox
for example,
     4U1234+56   12 34 35.3  56 01 02   1950
The window labeled Object Selector handles object lists. Clicking on Load New Object List opens a file dialog; once you select a file, the names of the objects appear in the selector box at the top of the window, and the objects themselves are also marked on the Sky Display. You can now select an object in one of three ways: When you select an object, its coordinates appear in the main window at the upper left. It will also be highlighted by a blue square on the Sky Display.

Note that you can view the list in alphabetical order, as well as sorted by RA.

More than one object list. When you read in a new object list with another already loaded, it's simply merged with the old list. If you have several long lists, the display gets too crowded. For this reason, there is a provision to remember the lists you've loaded and recall them quickly, without having to navigate down through the directory heirarchy. To use this, hit the "Clear List" button and then select the file you want to load from the lower list in the object list window. If it doesn't load, do a control-click to deselect it, then select it again -- lists only load when the selection changes, so if you click it when it's already selected, nothing happens.

The list-switching feature should be helpful if you have object lists for several different categories of targets -- these might be for different programs, or appropriate to different observing conditions, or something as simple as standard stars versus program objects.

The Telescope Interface window.

Moving the telescope to a new target. The slew telescope button in the 1.3m Telescope Interface window will move the telescope so that it is pointed at the RA and dec listed at the upper left of the main JSkyCalc window. The slew won't actually start until you confirm it with the dialog box that pops up. When you confirm the slew, the program sends a request to the server for the move; if the server is busy, or if the requested coordinates are illegal, the telescope won't move. Note that the program freezes up until the telescope has finished moving. Once the move is complete, you'll see that

Note that the Telescope RA, dec, and equinox that are displayed are passive displays of the telescope position -- they do not accept user input. In JSkyCalc convention, passive fields are rendered with a a light-grey background, while fields that accept input are rendered in white. Input coordinates need to appear in the boxes in the main window, in the upper left; those boxes are automatically updated when you select a target from a list.

Note also that there's a scroll box window that reports the telescope server's responses. You can usually ignore these, but it can be helpful to scroll back through them in case something unexpected happens (it keeps a couple hundred lines). If there's some kind of problem, you may find an ERROR lurking there -- for instance, you might be trying to slew past the telescope's limits.

A bit about Auto-update and Timing ... Unlike the usual JSkyCalc, this version starts up in auto-update mode, which means it wakes up every 15 seconds or so, reads the system clock and telescope coordinates, and redisplays everything for the current moment; it behaves like a very slowly ticking clock. It's possible to speed up the action by changing the 'sleep for' value, but I don't recommend it -- that just makes it more likely that things will screw up. If you're impatient you can use the Read telescope button to get an immediate update -- but remember that this won't respond if the telescope is slewing.

If you click on the orange "Stop Update" button on the main window, it stops the automatic updating, which makes it possible to look at times and dates other that the present. This may be helpful if you're thinking about tomorrow night, or something, but if you stop auto-update, the telescope control window disappears. This is by design, because you never want to slew the telescope based on information that may not correspond to the present time. If you resume the update again (simply by clicking the button), the telescope window reappears.

Looking up Bright Stars. The Nearest Bright Star button in the main JSkyCalc13m control window looks up the bright star nearest to the telescope coordinates (not the JSkyCalc13m coordinates, which might already be set on the next object or something), and loads them into JSkyCalc13m. If you now slew to these coordinates, you should be able to find the bright star (unless there's something wrong). The bright star list is kept in equinox 2000, but the coordinates have been updated for proper motion to 2010, so they should be more than good enough for setting the telescope coordinates. (I intend to freshen the list for proper motions from time to time.)

Re-zeroing the telescope coordinates. Be careful with this, since you can easily lose track of pointing if you don't do it right. If you click the Reset tel. coords, button, the telescope coordinate readouts will be reset so that they equal the coordinates displayed in the main window. Before you fire this command, you should be certain that both these conditions are met:

If either of these is false, the reset command will leave you hopelessly lost, and you will need to home the telescope at the zenith using the tilt meters.

The command works internally by resetting the zero points in the pointing model. It's best to do this not too far from the zenith, because the telescope flexure and so on are not very well modeled at extreme positions.

A step-by-step procedure for re-zeroing the coordinates might be:

"Situational Awareness" boxes. At the bottom of the telescope control window are boxes that simply report how long it will be until certain events happen. They show how long until twilight and sunrise (or sunset, if it's afternoon), until the telescope (if it continues tracking) will hit 2 and 3 airmasses in the west, and until the moon rises or sets. One box shows how long until the telescope hits the west limit (see below). In a few situations, the event reported is in the past; during evening twilight, for example the time since sunset is reported. During the day, the moonrise or set reported may be on the previous night, but during the day this won't matter much. This feature only makes sense when Auto update is in effect (as it is by default), so that the program's time is kept close to the actual time.

The West Limit. At declinations less than about 63 degrees, the telescope has an hour angle limit at just under 5 hr west, assuming it doesn't hit an elevation limit first. North of 63 degrees, the top ring of the telescope interferes with the north pier somewhere in the far west; for this reason a tripwire is installed that cuts the telescope power if the top ring deflects it enough.

The control software will not allow you to slew into the tripwire, but you can track into it very easily. This creates a real problem, because it normally takes two people to restart the telescope. To prevent this, JSkyCalc13mGS uses a tabulation of the measured west limit to stop the telescope tracking as the tripwire is approached. At lower declinations, the telescope doesn't hit the tripwire, but it still hits a soft limit, and the program takes this into account. At declinations south of the equator, the hour angle limit corresponds to a bit more than 4 airmasses. This far over, the telescope aperture is badly occulted by the dome wall, since the telescope swings under the pier.

The box labeled "Telescope at West Limit:" says how long you have left. If it's more than an hour, it's green; then it turns yellow, orange, and finally red when you have five minutes. If you hit the limit, the program

I highly recommend that you do this. If you click on "yes" in the dialog box, the telescope backs out of the limit by about an hour and a half, without changing the declination. The tracking is left off; the slew status button reminds you of this.

Warning Lights. At the bottom of the panel there three labels, "Sun:", "Moon:", and "Airmass:". Next to each is a little circle which you can think of as a warning light. The warning colors used are identical to those used for fields in the main window (and are explained in detail below), but they are computed for the telescope coordinates, not the coordinates in the main window, which may be different. If there's a situation you should be aware of -- twilight, you're too close to the moon, or the airmass is high -- these circles take on warning colors. Mostly their meanings are pretty obvious - yellow, orange or red -- but there are a few that are not:

Guide Star Selector. The button labeled Guide Stars on the main window pops up the window shown above. This shows the field of regard of the XY guide probe in the Multiple Instrument System. The coordinates of the field center (upper right) are taken from the main window. You select a guide star by clicking it in the image, and pushing the move guide probe button, which pops up a confirming dialog box to keep you from mistakenly moving the guide probe during an exposure. Acquisition and guiding is described in more detail here.

Reassurance. JSkyCalc13m operates independently of the telescope -- it just listens to the telescope and sends a limited set of commands. If JSkyCalc13m crashes, or you quit out of it, the telescope will still work fine. Hopefully the program will make your work more pleasant and efficient, but it isn't essential. So relax and enjoy using it -- it's not critical to anything.

Acknowledgments. It would have been nearly impossible to develop this program without using a companion program that mimics the telescope server communications; Rick Pogge (OSU) generously shared his simulator, and offered good advice. I also want to thank Bob Barr for help testing the program at MDM.

JSkyCalc has a huge number of other capabilities, some of which may be useful (e.g. the Nightly Almanac). The manual for the standard JSkyCalc follows.


What is this for?

JSkyCalc is a tool designed to help you plan and execute astronomical observations. It shares some features with "desktop planetarium" programs such as XEphem and its many commercial alternatives, but rather than elegant visual presentation, the program emphasizes convenient controls and calculation of the quantities of greatest interest to professional astronomers.

Getting Started

The control buttons at the bottom of the frame do the following; more detailed descriptions of some of the windows they pop can be found a little further down:

  • Refresh Output reads all the input values, computes everything, and refreshes all the output. The input values are overwritten with the values that the program used, and the the day of week is appended to the date.
  • Set to now sets the program time using your computer's clock, and refreshes the output. Step Forward and Step Back step the time forward or back using the value of the timestep (explained above).
  • Auto Update keeps the program close to real time -- it sets everything using Java's clock time (which is UT), sleeps for the number of seconds indicated in the sleep for (s) field, and then wakes up and updates again. Auto Step steps forward by the timestep, sleeps for the desired number of seconds, and then repeats. The sleep for field accepts only integers.
  • The Site Menu (which is displayed on startup) allows you to select among many of the world's major observatories. Changing sites causes the computations to be refreshed; the Universal time is kept the same, so the local time will jump if the offset from UT is different. If the desired site is not on the list you must enter its parameters in the fields in the main window, but you must first click the button on the site menu to Enable User Input. The DST code parameter is used to select the convention used for Daylight Savings time (if any). The US convention is 1 (but Arizona and Hawaii do not observe DST); negative numbers are used for southern hemisphere sites. [If you're using the program with WebStart, you're stuck with either using the pre-programmed menu choices or entering your own site's parameters every time; if you install the program locally, just find the file "skycalcsites.dat" and install your own site following the format explained there. The file "skycalcsites.orig" should be left untouched for use in case you inadvertently corrup "skycalcsites.dat". The skycalcsites.dat file must be kept in the same directory as the class files.]
  • The Planet Table gives low-precision positions of the planets (to about 1 arcmin for the inner planets, and several arcmin for the outer ones), in the epoch of date. The last column in the table, Proximity, gives the angular distance between the planet and the coordinates that are used in the main program.
  • Hourly Circumstances summarizes the observability of your object through the night. If the time is before local noon, the previous night is tabulated. This is among the most heavily used features..
  • The Nightly Almanac lists the times of sunset and sunrise, twilight, and moonset and moonrise, corrected for the Terrain elevation (of the observatory above its surroundings). The terrain elevation must be a positive number (this is checked on input and reset to zero if negative).
  • Seasonal Observability presents a table summarizing the observability of the object at each new moon and each full moon over a span of about 6 months centered on the program date.
  • Object lists ... lets you read in a list of your own objects, which you can then select from a menu or call by name from the Object field in the main window. They also appear on the Sky display, and you can select them there with a left mouse click. The Object List feature is extremely useful, but security features of WebStart prevent loading of object lists, so you need to install the program locally to make it work; fortunately, this is very straightforward.
  • The Sky Display gives a schematic view of the sky, with stars to V = 4.5 , the planets, the sun, the moon, and any objects loaded in the list indicated. You can control some things from the display window with mouse and keyboard commands -- holding down the right mouse button in the sky display gives a brief menu.
  • The Alt. Coordinates window gives the input coordinates precessed to the present equinox, the Galactic coordinates, and the ecliptic coordinates. If you type Enter in the Galactic coordinate field, the position in the main program is set to the galactic coordinates you give, that is, the program converts from galactic back to equatorial.
  • The Airmass Graphs window creates a display of airmass vs. time through the night. Local time is plotted at the bottom of the frame, and UT at the top. Airmass is plotted vertically, with low airmass (small zenith distance) at the top. The altitude of the moon above the horizon, is plotted in yellow, with little symbols indicating the phase. This is keyed to the yellow scale at the right-hand side of the plot (not the same vertical used for the airmass). A few non-obvious features of this tool:

    More detail on the Output Parameters

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

    More Detail on the Other Windows

    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
    for example,
         4U1234+56   12 34 35.3  56 01 02   1950
    The format is dictated by the telescope pointing list format expected at MDM Observatory, where I do most of my observing. Colons are acceptable as delimiters for the RA and dec fields (but be advised that they don't work with the MDM telescope software). The Load Object List button pops a file-selecting dialog box. Once you've loaded up a list, you can click on the object you want, and it will be loaded into the program. If you prefer, you can also select an object by typing its exact name into the Object: field in the main window and pressing the Enter key. You can present the list in either RA or alphabetical order using the buttons provided, and the Clear List button deletes all the objects (but for technical reasons, a single object called null at zero hours and zero degrees will remain). A hide button is provided also.

    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 Sky Display 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 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).

    It's a minor detail, but the stars are precessed to the current equinox whenever their coordinates are more than one year out of date; they are not precessed with every refresh to save computation time. One notices this with the 'h' command - the coordinates loaded will be close to the equinox of date, rather than (say) J2000. The planets, sun, and moon are already in the equinox of date. The object list is precessed with every refresh.

    Bugs, "Gotchas", and Limitations

    This is surely an incomplete list:

    About the Program

    This program is a re-implementation in Java of the venerable skycalc code, which is a text-only program written entirely in C. A couple of years ago 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. One version of this also has a sky display, which uses the Python wrapper around PGPLOT. This has proven extremely useful, but the software dependencies make installation complicated (and probably impossible on Windows), so I undertook the present effort for the sake of portability.

    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).