Documentation for GRAVITY.EXE
Program and Documentation (C)opyright Steve Safarik
Shareware Registration $30.00/$15.00 ($40.00/$20.00)
The Gravitational Simulator
Gravity version 2.0 is a powerful tool designed to simulate the
motions of planetary bodies in space. You may specify the
following parameters for up to 16 bodies: Mass, Density, Initial
position, and Initial velocity. The bodies are then plotted as
they move according to the laws of gravitation. You can view any
location in space at any magnification. You can also watch the
motion of a single planet via a "tracking" feature. Set up systems
and play "what if..." Elapsed time is optionally displayed, and
nearly every variable is available for user adjustment.
The primary design philosophy of this program was that it had to
be easy to learn and use by "mere humans". Sometimes that's hard
to do for a complex program, and I hope this version is as easy to
operate as version 1.0.
This program was first designed as a tool for people to use to view
the laws of motion and of gravity in action. After the first
release, users said that the main capability they desired was to
be able to enter actual planetary systems into the simulator.
Well, the reason no one could figure out how to do it, was because
"it just wasn't possible." So here we have version 2.0, a much
more powerful program with a number of added functions.
This documentation is organized as follows:
How to Register
Files you should have
Changes New to version 2.0
16 Random Planets
Clear all Planets
Central Planet Tracking
Show Orbits On/Off
Display Grid On/Off
Elapsed Time On/Off
Dynamic Time Interval
Screen Write Method
Util - Adjust Constants
Screen Center X/Y
Calculations per Plot
Central Planet Tracking
Util - Change Video Mode
Format for Numbers
Help with Setups
IBM compatible personal computer
Graphics display (Hercules, CGA, EGA, VGA, At&t, 8514/a)
Disk drive (Floppy or Hard)
At least 384K free memory after boot-up
note1: While this program will run in 384K free memory, some
functions may not be available, and you may run out of memory in
mid-simulation. I recommend having a machine with the maximum 640K
note2: A math coprocessor (80x87) will greatly increase the speed
of the running simulations.
How to Register
License registration fee is $15.00 for individuals, $30.00 for
government, corporate, and educational users (cheap). License fee
of $20.00/$40.00 entitles you to receive the next version by mail.
Only one registration per address is necessary and registers you
for future versions. Registered users of version 1.0 are
registered for version 2.0. This is shareware and as such may be
freely copied and given to others for trial use. Please help
support shareware authors.
Payment and other correspondence may be addressed to:
P.O. Box 45072
Seattle, WA 98145-0072
Let me know if there are any features you would like to see in
future versions. Suggestions from current users of version 1.0
were included in version 2.0, and I'm sure that there are many more
things people can think up. If you have any problems with the
program, remember: It's a feature, not a bug! If you find any
"features" that I didn't know about when the program was released,
please let me know.
Files You Should Have
GRAVITY.EXE The main executable file.
GRAVITY.DOC The documentation file.
GRAVITY.HLP Data file for on-line help.
*.GRV Miscellaneous saved setups (may or may not be
included with your copy)
Changes new to Version 2.0
1. Version 2.0 operates "True to Life". It is now possible to
enter actual systems and watch them execute.
2. A status line has been added to the running simulation.
3. Elapsed time has also been added to the running simulation.
4. Zoom capabilities have been added, making it possible to enter
systems which span small and large distances. For example,
our own solar system has distances as small as Earth-Moon and
as large as Sun-Pluto occurring at the same time. You may now
zoom-in and watch the inner three planets for example, or
zoom-out to see the whole system.
5. The maximum number of defined planets has been increased from
eight to 16.
6. You may view the simulation from either a fixed position in
space, or from the perspective of any one of the planets.
7. Context-sensitive help has been added for each data input
field by pressing F1.
8. Option added to automatically adjust the Time Interval
9. The inaccuracy that existed in version 1.0 in the calculation
of planet movements has been removed to a large extent.
10. Planets of zero mass, and single planets, now move properly.
11. Planet radius is smaller than the size of version 1.0 to more
truly reflect the actual size in relation to distances.
12. Planets created out of collisions now have velocity of a mass-
weighted average of the two previous planet's velocities (sum
of their momentums), rather than just an average of their
13. A planet density variable has been added for each planet.
14. You may now overwrite existing ".GRV" files.
When you first start the program, you will see the opening screen,
and then a row of choices at the top of the screen with these
FILE EDITOR GO EXAMPLES MISC UTIL
Move the menu-bar left and right and up and down with the arrow
keys, and select a choice with the ENTER key. The first thing to
do is select one of the examples such as "Moon" and watch it run.
Pressing Esc while it is running will stop the run and bring you
back to the menus. You can restart the simulation by selecting
"Watch it Running" under the "Go" menu. If you want to change any
values for planets, select "Planet Editor" under the "Editor" menu.
Context-sensitive help is available at any of the data-entry fields
by pressing F1. This will display text describing the values that
can be entered for that field.
File - Saving/Restoring Setups
Under the "File" menu, select "Save" or "Restore". Enter the full
path and filename of the file. If you do not specify a path, the
current directory is assumed. If you do not specify an extension,
.GRV is appended. Beginning with version 2.0 you can overwrite
save files. If the file already exists a prompt will appear on
whether or not you want to overwrite the existing file.
Unfortunately, .GRV files from version 1.0 are not compatible with
version 2.0. Many variables have changed and functionality has
been added so that even if the capability to read version 1.0 files
were included, the setups would no longer operate the same. This
program now operates "True to Life" and systems you enter should
be compatible with future versions.
--- Planet Editor: Values which can be changed individually for
each planet are: Mass, Density (new to 2.0), X position, Y
position, X velocity, Y velocity, Orbits on/off, and Stationary
on/off. Orbits enables the dots that mark the path of the planet,
while Stationary, when set to Yes, fixes the planet firmly in
place. Planets do not need to be entered as starting in view on
the screen (they did in 1.0), you may position them anywhere and
zoom-out to see them if you like.
Default value for all numerical entries is +0.00E+00 except for
density which is +1.00E+03 (1000). This is the density of water,
and can be left at that unless you are modeling an actual planet.
The density field is used only in calculating the planet radius
which, in turn, only affects collisions.
Version 1.0 allowed a maximum of 8 planets to be defined, while
version 2.0 allows 16.
New position values are not calculated for stationary planets.
This, of course, is a fabricated condition which should not be used
if you are modeling an actual system. The editor is pretty much
self explanatory other than that. When you exit, all variables are
reset to the editor values whether or not you made any changes,
just as if you had selected "Reset to Start". For information on
numerical formats entered here, see the section below entitled
"Format for Numbers".
--- 16 Random Planets: (New to Version 2.0) This selection will
erase all existing planets and create 16 new ones. Eight of them
will have mass 1.0e+18, and eight will have 1.0e+15. All have
density 1.0e+03 (water). The heavier ones will have velocity in
the range 0 - 1.0e-03 and the lighter ones will be in the range 0 -
1.0e-01. They will all start out visible on a screen at zoom
1.0e-07. "16 Random Planets" was created as sort of a last-thought
implementation to model a "gaseous cloud" which could turn into
some sort of orbiting system. I haven't really played around with
it much, and I don't know if it will be very interesting.
--- Clear All Planets: Will delete every planet and leave you with
one blank editor window open. Save your work before you select
There are now several functions available during the simulation as
--- Orbits: (New to version 2.0) The dots marking planet paths
are saved. You can exit a running system and change certain
variables (any of the constants, and any "Misc" selection), then
come back and still have paths plotted. The dots are saved in a
circular queue 8100 dots in length (8100 is determined by the 64K
segment limit of 80x86 processors). The saved dots will be erased
on any of the following conditions: changing any values in the
editor, selecting a sample setup, restoring a file, reseting to
start, or changing the video mode. If you watch from the
perspective of a Central Planet, the dots will be saved, but the
previously saved ones will not be drawn. When you switch back to
a fixed view, the saved dots will all be drawn. The display of
orbits can be toggled on and off with the 'O' key.
If you have a limited amount of free memory on your machine (less
than 200K after program start) the program will not save the dots
in order to conserve memory. Storing the 8100 dots requires 128K
--- Status Line: (New to version 2.0) While the planets are
moving on the screen you first press the 'S' key, then one of the
number keys on the keyboard, and the status for the corresponding
planet will be displayed on the top line. Pressing "S0" will turn
this function off. Values displayed are: Planet number, mass, X
position, Y position, X velocity, and Y velocity. Pressing the '0'
key or the number of a deleted planet will turn the status line
off. When planets collide, the status switches to the live planet
if one of the two was currently being displayed. Updating the
status line takes time and will considerably slow down the
simulation. Increasing "Calculations per Plot" may help with this.
For planet numbers 1 through 9, use the number keys. For planet
numbers 10 through 16, use the shifted keys 1 through 7,
respectively: ! @ # $ % ^ &.
--- Central Planet Tracking: (New to version 2.0) You can view the
simulation normally from a fixed location in space, or from the
perspective of any one of the planets. See information under
"Adjust Constants" below.
--- Elapsed Time: (New to version 2.0) The elapsed time (Earth
time) is displayed in the lower right. This function can be
toggled on and off with the 'T' key.
--- Zoom Box: (New to version 2.0) While the simulation is
running, you can use the following keys to change the zoom power
and panning values, thereby freeing you from manually spinning
numbers: PgUp, PgDn, Home, arrows, Enter, and Esc. PgUp makes the
zoom box smaller, PgDn makes the box larger, Home will zoom out
10X. Arrows move the box around the screen, Enter selects the new
values, and Esc aborts without changing anything. See section
below on Zoom Power for a description of zoom values.
--- Keys available during simulation:
Cn - Switches to tracking view for planet n
D - Toggles the dynamic adjustment of Time Interval
G - Toggles the grid on and off
O - Toggles display of orbits
Sn - Status display for planet n
T - Toggles the elapsed time display
To exit the simulation, press Esc. Previously, any key would exit.
The included example setups were modeled on the ones from version
1.0, but are not identical. The main differences are that
"Butterfly" has now become "Pendulum," and "System" is our own
solar system. I only tried to carry through the same general
principles as the previous examples of 1.0. You should be aware
that the examples are not perfectly accurate, and changing the Time
Interval will change their orbits. I am not an astronomer and
"System" is only a rough approximation of our own taken from values
in a 1978 physics textbook. If anyone would like to more correctly
model this and send me a copy, I could include it in a future
version of the program. If you send in any other systems, I can
include them as well.
--- Show Orbits (On/Off): Enables displaying of the Orbits that
mark the path of planets as they move. It takes priority over the
settings in the editor. The dots are always saved regardless of
this setting, except for planets whose Orbits Enable is N. This
setting is changeable from the running simulation with the 'O' key
--- Show Grid (On/Off): Enables drawing of the grid. This can be
useful for setting up a system, and also for making measurements
of planet paths. The Zoom Factor and Units will display in the
lower left, and the screen center coordinates will display near the
center of the screen. Units given are marked by the spacing on the
X and Y axes. Other markings are 10 x Units. This setting is
changeable from the running simulation with the 'G' key (toggle).
--- Elapsed Time (On/Off): (New to version 2.0) Enables the
display of elapsed time in the lower right corner of the simulation
screen. Time calculated is based on earth time and is displayed
as Years, Days, Hours, Minutes, and Seconds. The rate at which
this proceeds is determined by the value of the variable Time
Interval (in seconds). The clock rolls over to zero at 65536
years. This display may be toggled on and off with the 'T' key.
--- Dynamic Time Interval: (New to version 2.0) Automatically
and dynamically adjusts the Time Interval variable to provide the
best performance in terms of both speed and accuracy. A
calculation is made for each cycle to find the planet which is
moving the most in relation to its nearest neighbor, and thus being
the most demanding of precise calculations. The Time Interval is
then adjusted to give approximately a 1 to 10 ratio of distance
moved to distance from nearest neighbor. So all the planets will
slow down if one gets very close to another, or all will speed up
if they are all a long distance apart. This gives you more
accuracy when you need it most, and more speed when you don't need
the higher accuracy as much. The value of Time Interval is used
for the first three plots, but then switches to the calculated
values. This setting may be toggled from the running simulation
by pressing the 'D' key.
Note: Dynamic Time Adjustment seems to have the effect of
"circularifying" orbits, that is, turning elliptical orbits into
circular ones. It seems to be caused by losing some of a planets
energy at high orbits (by decreasing accuracy), and maintaining
energy at lower orbits.
--- Screen Write Direct/BIOS: Only functional for the menu
screens. If you get a weird display, set this to BIOS. The
graphics are all done direct to memory. Doing the graphics by the
BIOS would bring new meaning to the word "slow". This option may
also be chosen when you start the program with the command-line
Util - Adjust Constants
--- Zoom Power: (New to version 2.0) This is the magnification
of the screen. Normal magnification is 1.0 which will display
units of 1 meter. If you have some planets that are located a
large distance from (0,0), set Zoom to a number between 0 and 1.
A zoom power of 0.1 will plot everything at 1/10th the scale and
you can see objects located at ten times the distance you could
see before (units will be 10 meters). A zoom power of 10.0 will
make things look very big. One note however, if you try to zoom
in on one planet to make it look very big, it won't display larger
than a certain size. This is due to the memory requirement for
storing the planet's image that it be less than 64K in size. Also,
very large planets at normal zoom factors will display the same
way. This only affects the display of the planet, not the
calculations affecting collisions, etc. For keys available to
alter this value during the running simulation, see above section
on the "Go" menu.
If you get the message "Out of Memory" when you try to run your
setup, try using a lower zoom power. At higher zooms the images
of all the planets can take a substantial amount of memory (up to
64K each). Reducing the zoom power will reduce the total size of
all the planet images.
--- Screen Center X,Y: (New to version 2.0) This is the location
at the center of the screen, effectively a panning value. Default
center is (0,0). By using Zoom Factor with Screen Center you can
look at essentially any location in space at any magnification.
--- Time Interval: This is the length of time that a gravitational
force acts on a planet in seconds, or in other words, the time
elapsed between calculations for new velocity and position. The
planet motions are calculated at discrete intervals, the planets
aren't moving in curves, but in a whole lot of tiny straight lines.
The time interval relates to the length of those lines. Now out
in space those lines are really 0 in length, so the smaller the
time interval, the truer to reality this program will be. There
are two situations to use this. The first would be increasing this
to speed up the motion in the simulation, and the second would be
decreasing this to increase accuracy. Setting this too high will
make your system "explode" since those straight lines will be much
larger than the size of the orbits. This value can be determined
automatically by the program if you wish. See Dynamic Time
The smaller the radius of curvature of a planet the smaller the
value Time Interval should take. If the distance a planet travels
between plots is not more than 5-7 pixels, your accuracy is
probably fine. Set the Time Interval for approximately this
spacing, depending on which planet you are watching, and how fast
it is curving. For example, in "System," a smaller value will make
the inner planets move at a watchable speed, but the outer planets
will hardly move at all. Increasing the time factor will speed up
the outer planets so you can watch them move, but the inner planets
will then not orbit very true to reality... Bottom line: it's give
and take on speed versus accuracy.
--- Gravitational Constant: This is the strength of the
gravitational field induced by a mass. You should not need to
change this value, but it is available for versatility. This
value affects the units used for mass, density, distance, and
velocity. The value found in nature is +6.67E-11 N(m^2)/(Kg^2).
--- Calculations per Plot: (New to version 2.0) The name actually
isn't perfectly right. What you really change is how often the
planet is plotted on the screen. The frequency of calculation nor
the accuracy of the system changes. If you raise this number, the
locations will be plotted less frequently, but the path of the
planet will not change. There are three situations where this may
be of use. The first is for those of you who have slow display
hardware. You may be able to speed up your system by using the
display less frequently. The second situation this may come in
handy, is if you are at a large zoom factor and are watching a
planet which is slowing down your system. A big planet on the
screen takes a lot of memory, and memory takes time to move around,
so this may help. The last situation is when you are displaying
the status of a planet and things slow down. In version 1.0, this
value was automatically calculated at 0.60/(time interval) and this
is still the default (usually 001).
--- Central Planet Tracking: (New to version 2.0) You can watch
the system execute from the perspective of any planet. For
instance, you can watch the Earth/Moon system close-up with the
earth in the center of the screen without having to do
Zoom/Pan/Zoom/Pan/etc to keep chasing it around, or you can watch
the whole Solar System from the perspective of the Earth. You
enter the number of the planet you want to watch, with 00 watching
from a fixed location. If you are watching a central planet, the
variables "Screen Center X/Y" are overridden by the location values
of the planet. If the planet collides with another, the screen
switches to the live planet. Previously saved tracer dots will not
be plotted when centering on a planet, but new ones continue to be
saved and all will be plotted when you switch back to a fixed view.
This value may also be accessed from the running simulation by
first pressing the 'C' key, and then the number of the planet you
want to watch (1-9, ! @ # $ % ^ &). Entering "C0" will turn this
off and revert to the values in "Screen Center X/Y".
Util - Change Video Mode
If for some reason the program mis-detects your monitor type, you
can specify another type to use. You may also speed up your system
by choosing a lower resolution type than the one detected (i.e.
choose CGA on an EGA-equipped system). Beware that if you choose
a wrong type you will probably get a blank screen at best. This
selection can also be made when you start the program. Start
program with /? for a list of available switches.
Format for Numbers
When entering numbers into any input field you may use scientific
notation. If the field is wide enough, you can enter the number
normally (5000). To enter the number 1 billion (1000000000), use
1.0E9 which means 1.0 times 10^9. To enter .000000001, use 1.0E-
9. Notice that the exponent must be an integer.
Examples: 1.0E+12 is 10 times larger than 1.0E+11
5.7E+15 is 10000 times larger than 5.7E+11
2.0E+12 is 2 times larger than 1.0E+12
Please note that the total number of electrons in the Universe is
taken to be somewhere between 1E69 and 1E70, and it is recommended
that you don't use more than two digits in the exponent.
The sources of inaccuracy in this program are now narrowed down to
two items: Rounding error and discrete calculations. Rounding is
not of much significance in relation to any values that you may
encounter. The exception to this is the pendulum example which is
inherently unstable and falls apart after a number of cycles. If
you don't use stationary planets you should never see this effect.
The accuracy problem comes from making velocity and position
calculations at discrete intervals rather than continuously as
occurrs in space. You will see this error severely when you have
two planets approach each other very closely and the Time Interval
is not low enough to overcome the "radius of curvature" effect.
What will happen is that the two planets will experience a very
strong force towards each other, and would normally curve around
at high speed in a tight arc. If the Time Interval is not small
enough to accomodate this tight curvature they will experience this
large force for a much longer time than should be the case and will
go rocketing off in opposite directions. You can correct for most
of this by using the Dynamic Time Interval feature, although that
feature introduces a slight "circularifying" effect (see above
section on Dynamic Time Interval).
Help With Setups
Precision: One area where you may need a hint to enter a system
is when you have a very large distance coupled with a very small
distance and the precision allowed by the editor is not enough.
For example, how do you enter the Sun at (0,0), the Earth at a
LARGE distance from the Sun, and then the Moon at a SMALL distance
from the Earth? The trick is to not specify them all in the same
line, that is, not:
This way you can specify both the Earth and Moon as being the same
distance from the Sun on the X-axis, and then have more precision
available to specify the distance of Earth/Moon on the Y-axis.
This also allows for more precision in the specification of their
Total Energy: Planets in higher orbits have more total energy than
planets in lower orbits, even though the lower orbiting ones have
a higher speed. This is how spacecraft are able to "slingshot" out
of a system. They steal energy from an orbiting body by throwing
it into a lower orbit.
Total Momentum: To calculate the total momentum of a system,
multiply the mass of each planet with its speed. Then sum up the
results: M1xS1 + M2xS2 + M3xS3 + .... If the total momentum is not
zero, the whole system will "drift" through space. The positions
of the planets only come into play when calculating total angular
Technical Specifications version 2.0
Arithmetic: 64 bit floating point
Significant digits: 15-16 internally,
3- 9 externally (user input)
Overflow limit: +- 1.7E+308
Underflow limit: +- 1.7E-308
Maximum saved trace dots: 8100
Maximum defined planets: 16
Minimum horizontal resolution for text 600
Mass units: Kilograms
Distance units: Meters
Time units: Seconds
Density units: Kilograms per cubic Meter
Velocity units: Meters/Second
Gravitation equation: F = (G * m1 * m2)/(r^2)
Acceleration equation: a = F / m
Velocity equation: V = v + at
Motion equation: X = x + vt
Source files, total size: 173556 bytes
Executable size: 212608 bytes