Fabien Chéreau released the first version of Stellarium back in 2001 as a free, open source software package. Since then, developers have continued working to drive the software forward. Version 0.14.2 [1] was released in January 2016. Even so, version 0.13 is available in the source packages for all of the common distributions and is sufficient for most purposes. The current version has an advantage in that the developers corrected an annoying scripting error that had occurred in all previous versions. The software can be updated via the commands in Listing 1. A package or updates obtained from an unofficial source may contain defects.

$ sudo add-apt-repository ppa:stellarium/stellarium-releases
$ sudo apt-get update
$ sudo apt-get install stellarium
$ sudo apt-get upgrade

The concept underlying this software was introduced in a previous issue of Ubuntu User [2]. Additional user options deal with augmenting information about the astronomical objects and using scripting for controlling the display of the sky.

The basic Stellarium package contains data for approximately 600,000 stars with brightness of at least 10.5 magnitude (magnitude refers to the apparent brightness of stars). Under optimal conditions, humans can see around 6,000 stars, with magnitude 6 stars being the smallest discernible by the naked eye. This means that Stellarium displays the night skies as they are seen by the naked eye but also shows celestial objects that would otherwise be visible only through a telescope. For the user, the star catalogs offered by Stellarium are therefore important (see the "Star Catalogs" box for details).

Improving Stellarium

The software generates a status message when booted from the command line. For the first boot, the program should be called with the switch - -full-screen no . This setting disallows full-screen mode, thus making the terminal visible.

The option for installing extra data files about stars is found in the Configuration | Tools menu. Moving the mouse to the left edge of the window lets you select the suitable icon. Catalog 5 will add almost 2 million stars of up to magnitude 12. Catalog 9 extends the range to magnitude 18. A particular star with this magnitude is discussed later in this article.

The star catalogs for the basic version of Stellarium are found in the program directory /usr/share/stellarium/stars/default . Storing the catalog in this location prevents the user from accidentally making modifications. All of the extensions are stored in ~/.stellarium/ , except for the new stars, which are stored in ~/.stellarium/stars/default .

Large, real-life planetariums project displays of celestial objects by transmitting light through perforated spheres. Because these spheres are dependent on a single source of light, they cannot account for variations in the brightness of the objects. This shortcoming is remedied by using instruments to adjust the surface of each star according to its observed brightness.

Stellarium utilizes this approach as well. However the apparent size of the star reflects observations made by optical instruments, such as the human eye or a telescope equipped with a camera. Otherwise, it would be nearly impossible to recognize the stars and their colors. The program does have settings that permit the user to control the size of the star surface to a certain degree.

However, Stellarium distinguishes between objects such as planets, which have a discernible surface, and stars, which can look like mere points in the sky. More stars become visible as you zoom in on the sky with the mouse wheel. The surface area of the stars will barely change in appearance, but the planets will take on texture. The inner planets become illuminated as a crescent shape.

Larger stars come with an information box that contains their name. Clicking on the object with the left mouse button opens the box. Clicking with the right mouse button closes the box.

Controls in Hand

The Stellarium search function can be used to locate objects that are only visible when viewed through high-performance telescopes. Alternatively, the user can write a script that charts the coordinates for a target object and displays the path taken to arrive at the target as a small celestial show. (See the "Star Coordinates" box for more details.)

Adding data for stars of up to magnitude 18 makes it possible for the program to display even a small star at the correct location.

User-defined scripts are placed in the ~/.stellarium/scripts directory. These scripts are stored in text files. The scripting language uses syntax that borrows heavily from JavaScript. Therefore, the user should copy the instructions from Listing 2 into a text file and then save it with a suitable name and the extension .scc to the script directory.

core.moveToRaDecJ2000(-113.0564 , -0.8993, 0);

After restarting Stellarium, you can call the script via Configuration | Script . Any comments and error messages will appear in the terminal window. If necessary, the script can be edited retroactively. Changes are implemented without the need to restart the program. It suffices instead to stop the script, save the changes, and restart the script.

An initial invocation of the program may well be disappointing. Although Stellarium will point out the correct location in the sky, the Einstein ring may be covered by the day sky and the earth. Therefore, the user may need to use the mouse to switch the atmosphere, the foreground, and the clock using the icons in the menu at the bottom of the screen. If so, the user should turn the mouse wheel until the star appears. If an additional image of the Einstein ring has been installed, the display screen will look approximately like the example in Figure 1. Otherwise, only an inconspicuous point with magnitude 17.95 will be visible. As it turns out, this point does not actually represent a star, but rather two galaxies.

Figure 1: A script command can be used to point the virtual planetarium automatically to the Einstein ring.

The script in Listing 3 performs the same task as that performed by Listing 2, except that animation has been added. In line 18, the user will recognize the command from Listing 2, which positions the section of the sky at the correct star coordinates. The third parameter is non-zero and controls how fast the virtual telescope pivots. In this case, the pivoting occurs within 10 seconds.

01 // Name: Einsteinring SDSS J162746.44-005357.5
02 // License: Public Domain
03 // Author: rp 2016
04 // Description: Locate and zoom to the Einstein ring SDSS J162746.44-005357.5. In order to make the ring visible, the user first needs to add its image to the nebulae.
05
06 core.debug("Einsteinring");
07 core.goHome();
08 StarMgr.setLabelsAmount(3);
09 LabelMgr.deleteAllLabels();
10 label = LabelMgr.labelScreen("Einsteinring SDSS J162746.44-005357.5", 20, 20, false, 30, "#aa0000");
11 LabelMgr.setLabelShow(label, true);
12 LandscapeMgr.setCurrentLandscapeID("grossmugl",5);
13 LandscapeMgr.setFlagLandscape(true);
14 LandscapeMgr.setFlagAtmosphere(true);
15 core.wait(2)
16 core.setTimeRate(0);
17 core.debug("def. line of vision");
18 core.moveToRaDecJ2000(-113.0564 , -0.8993, 10);
19 core.wait(8);
20 core.debug("def. image detail");
21 StelMovementMgr.zoomTo(0.8, 15);
22 LandscapeMgr.setFlagLandscape(false);
23 LandscapeMgr.setFlagAtmosphere(false);
24 core.wait(10);
25 core.debug("display star labels");
26 StarMgr.setLabelsAmount(10);
27 core.wait(6)
28 core.debug("zoom in + display grid lines");
29 GridLinesMgr.setFlagAzimuthalGrid(true);
30 StelMovementMgr.zoomTo(0.01, 15);
31 core.wait(8)
32 label = LabelMgr.labelScreen("Diameter: 2 arcsec", 20, 60, false, 30, "#aa0000");
33 LabelMgr.setLabelShow(label, true);

Lines 1 through 4 are comment lines. The reserved words Name , License , Author , and Description are the identifiers that Stellarium inserts as short descriptions into the script.

The core.debug command in line 6 lists its parameters in the terminal output, which lets the user immediately figure out how far the script has advanced. Line 7 opens the view to the sky as if the program had just been started, and line 8 limits the output of labels to those for the large stars. For the higher magnifications in line 26, the program outputs all of the names known to it.

Line 10 writes its own text on the screen. Lines 12 through 14 control the appearance of the landscape. Line 16 stops the time; otherwise, stars shown at a high magnification would disappear too quickly from the display screen because of the earth's rotation. The program pauses for eight seconds in line 19 until the line of vision sets itself. Line 21 controls the magnification via the aperture angle. It takes 15 seconds to show a 0.8 degree section of the sky.

In line 30, the script zooms in further into the section of the sky. A short pause makes apparent the extent of magnification required for viewing the object. The grid lines (line 29) indicate the scale.

Sunrise

Stellarium also lets users experience spectacular sunrises. Figure 2 shows an intermediate step of a picture sequence generated by the script from Listing 4. At the beginning of spring, the user can experience twilight phases, including astronomical, nautical, and civil, occurring before sunrise.

Figure 2: Once supplied with the correct parameters, the virtual planetarium can show the various types of sunrise, such as the nautical twilight.

01 // Name:  Sunrise
02 // License: Public Domain
03 // Author: rp 2016
04 // Description: Simulation of Sunrise.
05
06 function displ(jd, mg){
07   core.debug("Info: "+mg);
08   core.waitFor(jd);
09   LabelMgr.deleteAllLabels();
10   label = LabelMgr.labelScreen(mg, 20, 20, false, 30, "#aa0000");
11   LabelMgr.setLabelShow(mg, true);
12 }
13
14 core.goHome();
15 label = LabelMgr.labelScreen("Sunrise March 21 at latitude 30°", 20, 20, false, 30, "#aa0000");
16 LabelMgr.setLabelShow(label, true);
17 LandscapeMgr.setCurrentLandscapeID("grossmugl",5);
18 LandscapeMgr.setFlagLandscape(true);
19 GridLinesMgr.setFlagAzimuthalGrid(true);
20 GridLinesMgr.setFlagMeridianLine(true);
21 core.setObserverLocation(0, 30, 1, 1, "", "Earth"); //Location of observer
22 core.wait(3);
23 core.setDate("2016-03-21T04:00:00", "utc"); //Target time
24 core.wait(3);
25 core.moveToAltAzi(10,110, 5); //line of vision
26 core.wait(3);
27 StelMovementMgr.zoomTo(100, 15); //section
28 GridLinesMgr.setFlagEclipticLine(true); //turn on ecliptic
29 core.setDate("2016-03-21T04:00:00", "utc"); //observation time
30 core.setTimeRate(130); //time lapse x 130
31 core.wait(2);
32 LandscapeMgr.setFlagAtmosphere(true);
33 displ("2016:03:21T04:44:00", "astronomical twilight (18 deg)");
34 displ("2016:03:21T05:10:40", "nautical twilight (12 deg)");
35 displ("2016:03:21T05:37:00", "civil twilight (6 deg)");
36 displ("2016:03:21T06:01:00", "sunrise");

The function in line 6 bundles recurring steps. With core.waitFor in line 8, the script waits until the point in time – which has been entered as a parameter – has passed. This function started working properly with the time lapse function core.setTimeRate() in version 0.14. The function combination did not work in previous versions. Line 21 sets the observation point at the 30th parallel. This can be changed to -23 degrees to find out why the sun rises so quickly in the tropics or to 67 degrees to change the location to the polar circle.

Variable Stars

The software also understands variable stars, which are stars that periodically change in brightness. The developers are planning visual displays of their variability for a future version of the software. Time-dependent luminosity for supernovas has already been integrated. This lets you observe that within just a few days, a star appears seemingly out of nowhere. The star then slowly fades away during the course of an entire year until it has largely disappeared. The current version of Stellarium simply indicates the supernova type from which it derives the typical variation in brightness.

The program updates the list of supernovae provided the corresponding plugin has been activated. Activating this plugin is accomplished by selecting the Load at startup option in Configuration | Plug-ins | Historical Supernovae . After restarting, open the submenu Configuration | Plug-ins | Historical Supernovae and click the configure button. Information about the most recent update to the list is found in settings .

The supernovae data is found in JSON format at ~/.stellarium/modules/Supernovae/supernovae.json . When this file is opened, the user finds the supernova SN 2014j with the positional information "09h55m42.087s" and "+69d40m26.54s" . This supernova event reached maximum brightness on the date given by 2456687 , which is a Julian Date (the number of days that have elapsed since January 1, 4713 BCE) equivalent to January 29, 2014.

When the user visits the corresponding location, there is practically nothing to see because the program merely shows a small star. To observe the explosion (Figure 3), the user will need to use the script from Listing 5. The coordinates in line 5 are given as a string in hexadecimal units. Line 9 defines the date on which the event started. The loop in lines 13 to 17 runs at two-day intervals during the subsequent 130 days. Line 18 marks the location of the explosion.

Figure 3: The light from the January, 2014, explosion of supernova SN 2014J in the M82 galaxy.

01 // Name: Supernova SN 2014J
02 // License: Public Domain
03 // Author: rp 2016
04 // Description: Supernova SN 2014J in M 82
05 core.moveToRaDecJ2000("09h55m42.087s" , "+69d40m26.54s", 0);
06 LandscapeMgr.setFlagLandscape(false);
07 LandscapeMgr.setFlagAtmosphere(false);
08 core.selectObjectByName("SN 2014j", false);
09 core.setDate("2014-01-01T04:00:00", "utc");
10 core.setMountMode("equatorial");
11 StelMovementMgr.setFlagTracking(true);
12 StelMovementMgr.zoomTo(0.3, 0);
13 for(i=0; i<130; i++)
14 {
15   core.setDate("+2 day");
16   core.wait(.1);
17 }
18 core.selectObjectByName("SN 2014j", true);

At the end of 2015, the media was full of news about the explosion of ASASSN-151h [3], otherwise known as SN 2015L [4]. This explosion was a hundred times stronger than that from a typical supernova, and astronomers are still trying to figure out where the energy for the eruption originated. Stellarium makes it possible for the user to experience what the researchers actually observed.

To show this event, you should add data for the hypernova from Listing 6 to the ~/.stellarium/modules/Supernovae/supernovae.json file (see the "Hypernova" box for more information.) When performing this operation, it is important to use the commas correctly. Too many or too few commas cause error messages, which the program outputs to the terminal window. Placing a comma after the last element is not allowed.

"2015L":
{
  "type": "Ia",
  "maxMagnitude": 16.3,
  "peakJD": 2457178.500000,
  "alpha": "22h02m15.490s",
  "delta": "-61d39m33.60s"

The script in Listing 6 lets you modify the location and date and obtain a version similar to that in Listing 7. You will probably need to start the script two times to perceive anything. Afterward, a small point will appear, briefly light up and then slowly fade away.

// Name: Hypernova SN 2015L
// License: Public Domain
// Author: rp 2016
// Description: Hypernova SN 2015L
core.moveToRaDecJ2000("22h02m15.490s" , "-61d39m33.60s", 0);
LandscapeMgr.setFlagLandscape(false);
LandscapeMgr.setFlagAtmosphere(false);
core.setDate("2015-05-01T04:00:00", "utc");
core.setMountMode("equatorial");
StelMovementMgr.setFlagTracking(true);
StelMovementMgr.zoomTo(0.3, 2);
core.wait(2);
for(i=0; i<50; i++) {
    core.setDate("+2 day");
    core.wait(.1); }
core.selectObjectByName("SN 2015l", true);

This event is truly fascinating for scientists because the hypernova and its galaxy are located almost 4 billion light years away from the earth. By way of comparison, the distance from earth to SN 2014J amounts to 10 million light years.

Conclusion

The simulations made possible by Stellarium are impressive. The software provides illustrations of current astronomical findings and also shows why it is so difficult to detect multiple small events in advance. The extensions open up far-reaching possibilities, and their syntax is not very complicated.