How to Run xrel

If you've succeeded in building xrel, running it is even easier, although you do have many options to control its behavior.

Command-line options

You can get a brief summary of the options below by giving the command

xrel -help

which will also show you the defaults for options that control simulation behavior.

Many options take an additional argument; the value that the argument represents is shown [in brackets] after the option name if so.

If specified, xrel will allocate a private colormap on a PseudoColor display. Has no effect on other types of displays. Overrides -colors.
Resize the window to fill the entire screen. This uses override_redirect to circumvent your window manager, so it's slightly dangerous because there's a chance it could prevent access to any of your other windows if the program freaks out. But it looks much cooler in a dark room.
-colors [number of colors]
Change the number of colors xrel tries to allocate on a PseudoColor display. If the requested number can't be allocated, it will use as many as it can successfully allocate.
-gamma [gamma correction factor]
Change the gamma correction factor. This affects the relative brightness of different intensities of a given color. Lower gamma values will make stars appear brighter and colors appear less saturated; higher values make stars appear dimmer and colors more intense. The default of 0.5 is about right for most displays. Most displays are likely to have gammas between 0.3 and 0.8.
Display a color test pattern instead of the simulation. Use with -size to get bigger patches of color. The color test pattern shows colors across several intensities and temperatures.
-size [dot radius]
Change the size of dots drawn to represent stars. -size 1 shows stars as single pixels; larger values correspond approximately to the radius of the circle drawn for a star.
-viewangle [angle]
Change the view angle covered by the display. The view angle is the visual angle subtended by the narrowest dimension of the view window.
-fps [frames per second]
Sets a maximum limit on the number of frames drawn per second. This may help you to get a consistent update rate or to limit the amount of CPU time and network bandwidth required for display updates. -fps 0, the default, means to draw at the maximum possible rate.
-stars [number of stars in universe]
Controls the number of stars in the "universe" of the simulation. Using more stars will slow down the simulation but give you more to look at.
-chunk [chunking factor for drawing]
Since xrel mostly draws dots into its window, and since X protocol requests for drawing dots have a fair amount of overhead, by default xrel "chunks" drawing requests together to reduce this overhead. This can make the update rate 1.2 to over 3 times faster than if "chunking" is not done (try "-chunk 1" and see for yourself). The default gives good results for typical cases. Increasing this number may improve drawing performance somewhat but can also cause a perceptible flickering; decreasing this number will help reduce the flicker but will also reduce the update rate.
-seed [random number seed]
Lets you set the random number seed used in random star generation, so you can duplicate the same random star field in different runs. If not specified, a semi-random seed is used and printed out for future reference.
-lattice [spacing]
Rather than generate stars in random locations, create a cubic lattice with alternating layers of red and blue stars [spacing] light-years apart. This may help you get a more quantitative picture of relativistic effects.
-velocity [initial velocity]
Set the initial velocity of your ship, as a fraction of c (in other words, you need to give a value greater than -1.0 and less than 1.0).
-accel [initial acceleration]
Sets the acceleration of your ship, in meters per second squared (9.8 = 1 Earth gravity).
-limit [speed limit]
When accelerating, stop accelerating if the ship's speed exceeds the specified limit (specified as a fraction of c). Note that this says "speed", not "velocity"; if you specify a limit of 0.9, your acceleration stops if you go above 0.9c or -0.9c.
Rather than stop accelerating at the specified limit, reverse acceleration instead. This simulates the appearance of a round trip between two different points in space.
-timescale [ratio of simulation time to real time]
Controls the rate at which simulation time elapses. The default, -timescale 86400, means that one second of real time equals one day of simulation time. Increasing the timescale speeds up the simulation. Very large timescales and very high velocities may produce weird results. Very small timescales produce extremely slow simulations.

Since xrel uses the X Toolkit command-line parser, you can use other standard X Toolkit options too -- for example, you can specify an alternate display with -display foo:0.0 or an alternate window size with -geometry 800x600+0+0. Consult your X window system reference for more details.

Changing defaults with X resources

Each command-line option has a corresponding X resource, so if you have defaults you'd like to change (say, gamma correction or star size) you can set those X resources to change them. xrel's application name is "xrel", and its class name is "Xrel". Each of its resources has the same name as the corresponding command-line option without the leading '-', so the X resource that controls gamma is called "gamma", for example. To change the default star size, gamma correction, and initial velocity and acceleration parameters of xrel for every time you run it, you could put something like this in your .Xresources or .Xdefaults file:

      xrel.size: 4
      xrel.gamma: 0.65
      xrel.velocity: 0.8
      xrel.accel: 0
      xrel.timescale: 3.1536e8

Note that command-line options always override X resources.

View controls

You can rotate your view left or right in 90-degree increments using mouse button 1. Pressing the button in the left half of the window rotates left; in the right half of the window rotates right. Pressing the 'r' key rotates 90 degrees right.

Pressing mouse button 2 or the 'p' key pauses the simulation. You can still rotate your view with the simulation paused. Pressing mouse button 2 again resumes the simulation.

Pressing mouse button 3 or the 'q' key quits the simulation.

The display window

The display window is simple. It shows you a view determined by your current view angle, and three lines in the upper left corner display your elapsed simulation time, your distance from the origin (where you started the simulation), and your current velocity relative to the stars.

Some examples

The compiled-in defaults simulate acceleration to 0.95 c at 1 Earth gravity (9.8 meters/second^2), with one real second representing one day of simulation time. Once you reach 0.95 c you continue to cruise through space at that rate.
xrel -bounce
Same as above, except that at +/- 0.95 c you reverse acceleration. Interestingly enough, this approximates the profile of a trip to Alpha Centauri -- you travel about 4.3 light-years between when you start at rest and when you come to rest again (relative to the stars).
xrel -acc 0.1 -times 1e8 -bounce
You probably noticed that you don't see any stars pass you in the above examples. That's because 1 Earth gravity of acceleration gets you up to near c within a distance that's fairly short compared to the distance to the stars near you, making it hard to see any parallax. With these parameters you accelerate much more slowly (hence the larger timescale to keep you from dying of boredom), travel farther (also more slowly), and actually get to see more stars pass you.

Return to Relativistic Starflight

Steve VanDevender
Last modified: Wed Feb 23 15:03:13 PST 2000