SpinDoctor

an artificial-gravity simulation program

screen image

Copyright © Theodore W. Hall

Permission is granted to make and distribute verbatim copies of this software and documentation provided the copyright notice and this permission notice are preserved on all copies.

The software is distributed as is, without warranty of any kind, either expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose.

Last update: 2010-11-13 19:33:00-05:00


Installation

Step 1:  Download the appropriate version for your system:

OS

Download

Remarks

IRIX 6.2 MIPS

sdr-irx-d.tgz

Requires FORTRAN, X11, and C dynamic libraries.  This version is linked like so:

f77 -O2 -s -o $@ ... -lX11

If you don't have the FORTRAN dynamic libraries and would like a statically linked version of this program, e-mail me and I'll try to put one together.  I may have to install the static FORTRAN libraries on my own system first.

SunOS 5.6 SPARC

sdr-sun-d.tgz

Requires FORTRAN, X11, and C dynamic libraries.  This version is linked like so:

f77 -O3 -s -o $@ ... -lX11

There's a minor bug in the Sun version: the rotation angle isn't clamped to the range ±π.  As a result, after several minutes of running, the argument to the sin() and cos() functions becomes quite large, and the motion becomes jerky.  I've fixed the source code, but in the meantime I've lost access to the Sun compilers.

sdr-sun-s.tgz

Statically linked to the FORTRAN libraries; still requires the X11 and C dynamic libraries.  This version is linked like so:

f77 -O3 -s -o $@ \
-B static ... -lF77 -lM77 -lsunmath \
-B dynamic -lX11

See the comment above regarding a minor bug in the Sun version.

Mac OS X 10.3 ppc

sdr-mac-ppc-s.tgz

Compiled and statically linked for the PowerPC.

No Cocoa, no Carbon, no Aqua -- just the same minimal X11 graphic interface, ported to the Mac OS X UNIX environment.  You'll also need an X11 window server for Mac OS X.  Apple includes one as an option with OS X 10.3.  If you're still running OS X 10.2, you can download a good free one from SourceForge.  You must first launch the X11 server; then start "SpinDoctor" or "sdr" (a symbolic link) from the XTerm command line.

Mac OS X 10.6 i386

sdr-mac-i386-s.tgz

Compiled and statically linked for the Intel.

No Cocoa, no Carbon, no Aqua -- just the same minimal X11 graphic interface, ported to the Mac OS X UNIX environment.  You'll also need the X11 window server, included as an option with OS X 10.6.  You must first launch the X11 server; then start "SpinDoctor" or "sdr" (a symbolic link) from the XTerm command line.

Linux

Not available

Sorry, I haven't ported this to Linux yet.  If there's sufficient demand, I'll try to supply.  E-mail me.

Step 2:  Unpack the ".tgz" file.  This will create a directory that contains the program and a copy of this document.  In the following, replace archive with the basename of the archive you downloaded in Step 1:

gunzip archive.tgz; tar -xvf archive.tar;

Mac users: Stuffit Expander basically works, but it handles file extensions differently.  You may end up with several "sdr-mac-*" folders.  The one to keep is the one that contains 9 items.  The "gunzip" and "tar" commands in the UNIX command line shown above (typed in the Terminal app) are consistent with the other UNIX platforms.


Operation

Program Layout

screen image

The program opens a new window with several graphic and text areas, referred to below as "boxes".  Numbered left-to-right and top-to-bottom, they are:

Box 1

Artificial gravity, Rotating view.

Box 2

Artificial gravity, Inertial view.

Box 3

Planetary gravity (Earth by default).

Box 4

Vector control for the initial height and velocity of a free-falling particle.  See the sections on Particle Control and Vector Control.

Box 5

Slider for habitat radius, in meters.  See the sections on Rotation Control and Slider Control.

Box 6

Slider for habitat rotations per minute.  See the sections on Rotation Control and Slider Control.

Box 7

Slider for habitat gravity factor.  See the sections on Rotation Control and Slider Control.

Box 8

Messages and prompts.

Box 9

Text input for the initial height and velocity of a free-falling particle.  See the sections on Particle Control and Text Input.

Box 10

Text input for the radius (in meters), rotations per minute, and gravity factor.  See the sections on Rotation Control and Text Input.

Command Keys

<Ctrl>C

Exits the program.

<Esc>

Exits the program.

<F1>

Launches a particle.

<Shift><F1>

Toggles auto-launch.  In the Message window (box 8), the program prompts for a "time increment" in seconds.  See the section on Text Input.

<F2>

Toggles stop-action.  Useful for grabbing frames from the animation.

<F3>

Sets the Planetary gravity to "Variable".  In this mode, the intensity of the Planetary gravity (box 3) equals the intensity of the Artificial gravity (boxes 1 and 2), set by the gravity-factor controls.  This is useful, for example, for comparing Mars-intensity artificial gravity to actual Mars gravity.

<Shift><F3>

Resets the Planetary gravity to "Earth-normal".  This is the default.

<F4>

Writes a plot file.  In the Message window (box 8), the program prompts for a "plot file name".  See the sections on Text Input and Plot Files.

Particle Control

Specify the initial Height, Velocity, and Angle of the free-falling particles, in meters, meters per second, and degrees of elevation from "east" (prograde).  You may control these parameters either graphically (box 4), or textually (box 9). 

The three values are independent.

Rotation Control

Specify the Radius (meters), the RPM (rotations per minute), and the G-factor (multiples of Earth gravity).  You may control these parameters either graphically (boxes 5, 6, 7) or textually (box 10).

These parameters are inter-dependent: specifying values for any two of them determines the value of the third one as well.  Whenever you assign a value to any of the parameters, that parameter receives the highest priority.  The program then recomputes the parameter with the lowest priority (least recently specified by you), according to the values of the other two. 

The equations are:

   pi     = 3.14159265358979323846

   A      = G * 9.80665              meters  / (second^2)
          = Omega^2 * Radius

   Omega  = RPM * pi / 30            radians / second
          = sqrt (A / Radius)

   Radius = A / (Omega^2)            meters

Vector Control

Use the mouse in box 4 to drag either the head or the tail of the vector.

Press on the small green particle to select the tail of the vector.  Drag the particle vertically up or down to set its initial height (in meters).  Horizontal displacement is ignored.  The particle's initial velocity and angle are unaffected - the head of the vector moves with the tail.

Press anywhere else in box 4 - away from the particle - to select the head of the vector.  It's not necessary to be near the head.  This allows you to distinguish between the head and the tail when the vector has zero length.  Drag the head anywhere within the box to set the particle's initial velocity and angle.  The initial height is unaffected.

To accommodate a convenient human scale for both height and velocity, the graphic velocity unit is 10 meters per second.  (This affects only the length of the vector in box 4, not the numeric value in box 9.)  The viewport allows an initial height of 10 meters, and an initial horizontal velocity of 50 meters per second, either prograde or retrograde.  A 90-mile-per-hour fastball corresponds to about 40 meters per second.

Values that are out-of-range graphically may be input as text in box 9.  The graphic vector is clipped to box 4.

Slider Control

Use the mouse in boxes 5, 6, 7 to drag the vertical sliders for Radius, RPM, and G-factor.  The sliders are scaled to accommodate an "interesting" range of values, both inside and outside of the supposed "comfort zone" for rotation.

Values that are out-of-range graphically may be input as text in box 10.  The sliders are clamped to boxes 5, 6, 7.

Text Input

The prompt field in box 8 is arbitrarily long, depending on the program's window size.  The numeric fields in boxes 9 and 10 allow six characters.

The user interface is a bit quirky.  (See the section on History.)  Briefly:

Fun and Games

The most interesting effects occur when you throw the particles up and against the rotation, especially when the radius is small.  Play with small radii and fast rotations and see why these are uncomfortable.  (The artificial gravity is quite unnatural.)  Make up your own games.  For example:

Caveat

The purpose of this program is to illustrate the "shape" of the artificial gravity field.  It is not a complete simulation of particle physics.  In particular, it does not consider atmospheric effects; it animates the particles as if they were in a vacuum.  For low relative velocities, at the "human scale", this is close enough.  However, with large relative velocities or long distances, the rotating atmosphere may exert a significant force on a moving body, depending on the body's size, shape, and density.  Atmospheric effects are beyond the scope of this program.

Plot Files

The plot file format is a relic of the Merit computer network at the University of Michigan.  It was designed to describe simple pen plots in a text format.  The files rdplot.c and rdplot.f contain sample program source code, in C and FORTRAN, for reading and decoding the plot file format.  You're on your own to modify those programs to actually produce graphic output.

I've considered revising the plot function to produce a PostScript file.  I have a function library for creating PostScript files, but it would take moderate effort to revise this program to use it.  If that's something you'd like, e-mail me.  The squeaky wheel gets the grease.

History and Miscellany

I originally wrote this program as part of my doctoral research, in 1987, in the Architecture and Planning Research Laboratory (APRL) at the University of Michigan.  I wrote it in FORTRAN 77 on Apollo workstations running the Aegis operating system, the Apollo Display Manager (DM), and the Apollo Graphics Primitives (GPR).  The X Window System, xlib, xt, and Motif were not available.  I wrote all of the interaction - the vector, the sliders, the text input - from low-level events and graphic primitives.  Thus the program's somewhat quirky non-Motif look and feel.

This program links to an APRL utility library to handle text input and convert characters to real numbers.  Originally, the character-to-real converter was a fairly small subroutine that handled only signs, digits, and decimal points.  Later, Jim Turner and I replaced its guts with a call to a home-grown subsystem that handles general algebraic expressions.  Voila!  Virtually every APRL program that prompts for real-number input can now accept those expressions.  This program inherits that feature, though its small text fields don't allow for much of an expression.

In other work, Eduardo Sobrino and I wrote a function library to emulate Apollo GPR through xlib, allowing us to port APRL programs from the Apollo to X workstations.  This program also links to that library.  It looks and feels in X essentially the same as it did in Apollo GPR.

This program generally tries to open a new full-size child of the root window.  In my experience, with SGI 4Dwm and Sun CDE (both apparently Motif derivatives) the window is appropriately resized to accommodate the window manager's decorations.  With Sun OpenLook, the window manager's decorations may be clipped.  You can still move and resize the window if necessary.

For Apollo aficionados:  By default, the program initializes graphics in GPR_$BORROW mode.  In true GPR, that's roughly equivalent in X to grabbing the server and drawing on the root window.  In X, that would be considered pretty rude.  The xlib GPR emulator normally handles GPR_$BORROW by opening a new full-size child of the root window, managed by the window manager (Motif or whatever).  You can override the window manager by setting the environment variable GPR_BORROW to "STRICT" before running the program.  For example, in csh:

setenv GPR_BORROW STRICT

The GPR emulator then sets the xlib window's override_redirect attribute to True, resulting in a true full-screen window without manager decoration.  It looks like true GPR_$BORROW, though the window is still a child of the root (not the root itself), and the program still doesn't grab the server.

The command-line option -d causes the program to initialize in GPR_$DIRECT mode.  It opens a new large window (nearly full screen) and initializes graphics in that window.  In true Apollo GPR, this is necessary if the program is to share the display with others; it must "acquire" the display before performing any graphic I/O, and "release" the display (allowing others to acquire it) before a certain maximum time expires.  In the GPR emulator, the end result is essentially the same as the default GPR_$BORROW without "STRICT", except that there is some additional overhead in emulating the "acquire" and "release" functions (including raising the window, installing the color map, and setting the event mask).


HTML 4.0     CSS 2