by Sky Coyote, December 2009
(iPhone is a trademark of Apple, Inc.)
Quick start: Go to the Examples view and play. Tap to select an example, and
then tap the 'Load' button. In the Motion view, the go/stop button is at lower
right (triangle and then a square). While the simulation is running, be sure
to tap and drag left-right and up-down to rotate the display. Zoom buttons are
at upper left and right. It may help you to read about the examples in section
5 of this manual. Alas, reading the rest of this manual is probably a good idea
too. Enjoy!
Contents:
Welcome to the Nbody motion simulation application for the Apple iPhone! This
program simulates the motion of N masses acting under the influence of gravity
according to the equation force = -G * mass1 * mass2 / distance^2, where G is a
gravitational constant, mass1 amd mass2 are each pair of masses in the
simulation, and distance is the distance between the two masses. The force
between each pair of masses is summed up for each mass to determine that mass's
net acceleration (by acceleration = force / mass), which is then used to
calculate the corresponding change in that mass's velocity and position over 1
DT (delta time unit) of the simulation. The integration method used to
calculate velocity from acceleration, and position from velocity is the
'classic' 4th-order Runge Kutta method, which is described in many online and
printed textbooks. In addition, a correction is applied to maintain a constant
total energy (= potential energy + kinetic energy) in the system of masses, if
possible.
NOTE: All units used in this program are in terms of distance in meters, mass
in kilograms, and time in seconds (MKS units).
The user interface to the Nbody application consists of 5 different views or
displays:
-- The Motion view, which shows and animation of the moving masses.
When the Nbody application first starts, it loads one of the pre-created
examples called 'Fanfare'. When you quit the application by pressing the Home
button, (or iPhone OS terminates the application with notice) the current state
of the display and all settings are automatically preserved in a file, and then
automatically reloaded the next time you start the Nbody application so that
you can continue your experiments from the point you left them.
The Motion view shows the current and past positions (if trails are shown) of
all masses in the simulation. It can also show the orientation of the
coordinate axes, located at the origin of the coordinate system (= center of
the display). If the axes are visible, they are shown in red (x axis), green (y
axis), and blue (z axis). The orientation of the display can be changed
(rotated) at any time by tap-dragging (one finger only) on the screen. Drag
left and right to change the azimuth of the display, drag up and down to change
the altitude. The display can be rotated while the simulation is running.
There are 5 circular buttons in this view. They are:
-- Zoom out (at upper left). Tap to decrease the magnification (make smaller)
of the display.
NOTE: 2-finger gestures (e.g. 'pinching') cannot be used to zoom in and out.
Only the buttons can be used.
-- Reset axes (at lower left). Tap to return the orientation to azimuth = 120
degrees, altitude = 20 degrees, magnitude = last set in Settings view. Tap
this button if you have been rotating and zooming the display quite a bit, and
are 'lost' as to its orientation.
Three numbers are displayed at the top of the screen:
-- Simulation time in seconds (at left).
NOTE: In general, the total energy (potential + kinetic) should be constant
throughout the simulation (although this is not always possible due to the
discreteness of the simulation), although the values for potential and kinetic
energy will change depending on the speed of the motion. For the system of
masses to remain bound together, the total energy should be negative. If the
total energy is positive, the masses may escape to infinity and never return
together. If the total energy is non-negative, the two numbers are displayed
in red, otherwise they are displayed in white.
NOTE: Tapping the tab bar to go to another view stops the simulation, but does
not reset it.
The Settings view allows you to change the values of variables used to control
the simulation. Values can be entered in normal decimal notation, or in
scientific notation (e.g. where 1.23e-4 = 1.23 x 10^-4). Only 6 decimal digits
are displayed in the text fields. These variables are:
NOTE: As a convenience, the numerical text fields interpret the '@' character
as 'e', so that to enter a value in scientific notation such as 1.23e-2, type
'1.23@-2'. The 'e' character also works, but must be accessed from the ABC
keys of the keyboard.
-- G: The gravitational constant. For small-scale demonstrations, a value of
or close to 1 is generally acceptable. However, the actual physical value of G
is = 6.67e-11. This is the smallest value which can be used in the Nbody
program. An easy way to set this value is to type zero (or nothing) into the
text field for G, and it will be reset to this minimal value. Allowed values
are 6.67e-11 to 1e6.
-- DT: The simulation timestep, in seconds. A nominal value of about 0.025 is
usually good. Decrease this value for more precision in the motion
calculations. Allowed values are 1e-6 to 1e7.
-- Trail length. The number of past positions shown for masses which have
their individual trail settings on. Allowed values are 0 to 10000. Set this
to 0 to remove trails from all masses.
NOTE: Displaying longer trails will significantly slow the simulation speed,
due to the graphics overhead, irrespective of DT.
-- Max acceleration. The maximum acceleration of any mass, in m/s^2. Forces
which would generate greater accelerations are clipped to this value. For most
simulations, a value of 10 is useful. Earth surface gravity has an acceleration
of 9.8 m/s^2. Allowed values are 1e-6 to 1e6.
NOTE: Due to the inaccuracy of the math, and the inherent discreteness of the
simulation, masses which pass close to one another will have a tendency to
experience greater than realistic accelerations, will pick up kinetic energy,
and may fly apart. To reduce this problem, all accelerations are limited by
the value set above. You can experiment with different limiting acceleration
values to see when different configurations will tend to become unstable.
-- Axes origin: Can be set to one of three values:
NOTE: In general, setting the axes origin to the centroid (center of all
masses) will keep them centered in the display as they move around, although
then the axes themselves, and any fixed masses, will appear to move.
-- Show axes. Display the coordinate axes (red = x, green = y, blue = z).
-- Transform trails. When off, all past positions are displayed as their 'raw'
x, y, and z values, which may make them appear to move around over time when
the axes origin is not set to {0, 0, 0}. When on, all past positions are first
transformed to the axes origin which was in effect when they were saved.
Generally, this is what you want to happen if you have set the axes origin to
the centroid or a particular mass, and you want to see closed orbits.
NOTE: There are more settings below the 'Transform trails' switch. Scroll down
to see the additional settings.
-- Axis length. The length (in meters) of each coordinate axis. The default
setting is 1 meter. Allowed values are 1e-6 to 1e6.
-- Mass density. In kilograms per meter^3. The density of water is 1000, and
the density of the Earth is 5515. This value determines the size of the balls
displayed in the Motion view, although the minimum display size of any mass is
radius = 2 pixels and the maximum size is radius = 100 pixels. This value has
no other effect on the simulation, since the individual masses are set directly
from the Masses view.
-- Max updates/sec: The maximum number of simulation steps per second displayed
in the Motion view. Depending on your iPhone model, the number of masses, and
whether trails are displayed, this actual value may be quite lower than you
would like. However, for small simulations on fast devices (e.g. 3GS), it can
approach 100 frames-per-second. Use this value to limit the number of screen
refreshes so that you can easily see the motion of all masses. Timed intervals
between refreshes are the reciprocal of this value. Allowed values are 1 to
100.
-- Magnification: The multiplicative relationship between distance and pixels.
The default value of 150 makes a 1 meter axis 150 pixels long. You can set
this value to change the display magnification more quickly than by tapping the
zoom buttons in the Motion view. This value will also be used when you tap the
'reset axes' button in the Motion view. Allowed values are 1e-11 to 1e6.
Tap the 'Save' button to save your changes to these settings.
NOTE: Your settings are not applied until you tap the Save button. To cancel
editing, simply tap the tab bar to go to another view.
This view shows a table of all the masses in the current simulation, and allows
you to add or delete masses, and edit the settings for individual masses.
Scroll down to see all the masses if there are more than 8. The mass and
initial position of each mass is shown in the table.
Selecting a mass in this view causes the corresponding ball in the Motion view
to be marked by a surrounding yellow circle and crosshair. Tap the mass row
again to deselect it.
Tap the '+' button at upper left to create a new mass at the end of the table.
New masses are created with random initial positions and velocities in the
range -1 to 1.
NOTE: An Nbody simulation can have a maximum of 100 masses.
Select a mass and tap the trashcan button at upper right to delete the selected
mass.
NOTE: You will not be asked to confirm a deletion, so make sure you want to
delete a mass before selecting it and tapping the trashcan button. Also,
whenever you create or delete a mass, the simulation will be reset to its
initial configuration.
Tap the '>' button at the right of a row to edit the settings for that mass.
There are 2 screens of settings for each mass, shown by tapping the 2-segment
button at upper right. The 'XYZ' screen shows the following settings:
-- Mass: The mass in kilograms. Any non-negative value is allowed. To create
a 'test mass' which responds to gravity from other masses, but which exerts no
gravitational force of its own, set the mass to 0.
-- X0, Y0, Z0: The initial position of the mass. This is where the mass will
start, and where it will go when you tap the 'reset' button in the Motion view.
Any values are allowed.
-- VX0, VY0, VZ0: The initial velocity of the mass. This is the velocity
(speed and direction) the mass will have when it starts, and when you tap the
'reset' button in the Motion view. Any values are allowed.
NOTE: You cannot set the current position or velocity of a mass, only its
initial position and velocity. Also, remember that these values will not have
an effect until you reset the simulation.
Tap the 'Save' button to apply these values for the edited mass. To cancel
editing, simply leave the editing view without tapping Save.
The 'More' screen shows the following settings:
-- Show trails: Set to 'on' to show trails for this mass. Note that you must
also enter a non-zero number in the 'Trail length' setting of the Settings view
for trails to appear.
-- Fixed position: Set to 'on' to make this mass immobile. Fixed masses exert
gravity on other masses, but are not affected by gravity. Fixed masses may
appear to move (and can leave trails) if the 'Axes origin' setting in the
Settings view is not set to '{0, 0, 0}'.
-- Color: Tap and drag across the color planes to select a color for the mass
and its trails. Note that you can set a mass's color to black, and it will not
be visible in the Motion view, except when it obscures other masses.
Tap the 'Save' button to apply these values to the edited mass.
NOTE: Tapping the Save button will save all settings for a mass, from both edit
screens. You only need to tap the Save button once.
The Examples view shows a table of all of the simulations that have been built
into the Nbody program, those that you have saved permanently into iPhone
memory ('on disk'), and an example which might be in the iPhone pasteboard. You
can load examples, save the current example to memory or the pasteboard
(export), or delete an example which is in memory or the pasteboard.
To load an example, select it by tapping its row, and then tap the 'Load'
button. (To deselect an example, tap it again.)
The built-in examples consist of the following. Examples marked '(Random)' are
initialized with a slightly different random configuration each time you load
them:
-- Fanfare: Demonstrates the use of fixed and moving masses. This shows the
range of motion possible with a simple configuration. Back in the Motion view,
the 'Go' button is at lower right. Tap and drag left-right and up-down to
rotate the display to follow the motion. If you get lost, go to the settings
view and turn on the 'Show axes' switch and click 'Save'. The 'Reset' button
is next to the 'Go' button at lower right. Reload this from the Examples view
again to get a slightly different simulation. (Random)
-- 0-body: A quick way to delete all masses and reset variables for use in
building your own examples. Does nothing on its own, without creating new
masses.
-- 2-body: A canonical 2 mass system with elliptical orbits. Try slightly
varying the value of G, and then the value of one of the masses to see the
effects on the motion. Then, set the axes origin to 'centroid' or one of the
masses, using both untransformed and transformed trails to see the difference.
Reset to the original configuration and add a third 'test' (mass = 0) mass at x
= y = 0, z = 1, vx = vy = vz = 0 to see a chaotic 'pogo' effect as you change
the value of G. Then give this mass a non-zero value, and then offset it
slightly from x = y = 0. Use a smaller DT to get a more accurate result.
-- 3-body: A random but 'reasonable' 3 mass system (i.e. one that does not
immediately 'explode'), displayed using transformed centroid coordinates. Many
will degenerate into a 2-and-1-mass system (a binary orbiting a single), or
will eject a mass, but many others will produce long-term interesting 3-body
motion. If you don't get one you like, try, try, again! (Random)
NOTE: This is a convenience example. You can create any random N-body system
by loading the 0-body example and then adding masses in the Masses view.
-- Collapsing cloud: This shows the interaction of 100 masses with no initial
velocity collapsing under their own 'weight', although there is no central
mass. Try altering the mass and color of one or more of the masses. Try
decreasing the maximum acceleration to prevent 'explosions'. Turn on one of
the trails, and then 'Transform trails', to see a random walk. (Random)
-- Rainbow planets: This starts in a 'geocentric' configuration with the
display centered on one of the planets (all massless). Set the axes origin to
{0, 0, 0} to see the circular motion. Set the mass of one planet to a small
non-zero value to see the effect on the other masses. Change the initial
position and velocity (from +x to -x and +vy to -vy) to delay the effect on the
overall motion. Add a z displacement to a mass. Redisplay in geocentric
coordinates.
-- Sun-Earth-Moon: Kind of boring, but demonstrates that one mass can be in
orbit about another, and can in turn have its own stable satellite (with yet
another satellite). The DT value is 1/2 hour. Set to geocentric coordinates
and zoom in on the Earth to see the moon and its own satellite. Set to
lunar-centric coordinates to see the lunar satellite orbit. Use untransformed
trails to see the actual paths of all.
-- Earth-Moon + Lagrange points: Shows how most other positions in the same
orbit occupied by a mass are unstable, with some notable exceptions. Also
shows the occurrence of 'horseshoe orbits' and particles which transit from one
side of the 'ring' to the other. Reload and run this several times to see the
pattern from slightly different initial configurations. The Earth and Moon are
shown at exaggerated sizes. (Random)
-- Solar system: Simplistic circular orbits of the 9 planets, but using
inclination and ascending node longitude. DT is set to two days. Zoom in to
see the Earth and inner planets. Switch to geocentric coordinates (mass 4) to
see retrograde motions (e.g. 3 per year for Mercury). Delete the inner planets
and increase the DT to see the full orbits of the outer planets. (Random)
-- Black hole: A bunch of test masses orbiting an invisible central mass. Set
one of the orbiting masses to a small non-zero value for slingshot activity and
eventually a 'starburst' effect. Make this mass even bigger, set its color to
black, and turn off its trails for two orbiting 'black holes'. (Random)
To delete an example, select it by tapping its row, and then tap the 'Delete'
button. You will be asked to confirm the deletion.
NOTE: You can only delete examples which you have saved into memory, or which
are in the pasteboard. You cannot delete a built-in example.
To save the initial conditions and settings of the current example, tap the
'Save' button. You will then see a screen which prompts you for a location to
save (either a file in memory, or copy to the pasteboard), the name of the
example, and a short description which will be displayed in the table below the
name. Once you have selected a location, entered a name and a description, tap
the 'Save' button. Only the initial conditions (positions and velocities of
masses) and settings are saved. Tap the 'Cancel' button to return to the
Examples view without saving.
NOTE: Although you can type any character into the name or description field,
characters other than letters, numbers, spaces, underscores, or dashes will be
removed from file names, and spaces will be converted to underscores (and
converted back to spaces in the Examples view). Do not put an extension at the
end of a file name. Nbody examples are text files, and the .txt extension will
be added automatically, and all others removed. Names and descriptions are
limited to 32 characters.
You can import and export Nbody examples by using the iPhone pasteboard. For
example, if you save the current example to the pasteboard, quit the Nbody
application, start up the Mail application, and paste the contents of the
pasteboard into your email message, you can send the example to someone else.
Again, only the initial conditions and current settings are saved.
Conversely, if you receive the text of an Nbody example via email, you can copy
it to the pasteboard and it will show up in the Examples view in a section of
the table entitled 'Example in iPhone pasteboard'. You can then select, load,
or delete this example. Pasting another example into the pasteboard replaces
the one already there, if any.
NOTE: If your email program reformats the text, you may need to edit it to
import it correctly. In particular, lines beginning with 'Mass = ' must not be
broken up over several lines. All lines must end with the '\n' newline
character only. See the website listed in section 7 below for more information
about importing Nbody text examples.
You can also download an Nbody example from a website using Safari, also by
copying it to the pasteboard. For an example of this type, see the companion
website listed in section 7.
(Safari is a trademark of Apple, Inc.)
NOTE: The topic of creating or editing Nbody examples as text strings is beyond
the scope of this manual. See the companion website listed in section 7 for
details of how to create or edit Nbody text examples for importing.
The Info view simply shows this user's manual.
The following website (tap the link below to open Safari) contains:
-- News about the Nbody application and other programs.
http://www.skycoyote.com/Nbody/
Please send comments and bug reports to:
nbody@skycoyote.com
I apologize in advance that I cannot reply to every email.
-- The Settings view, which allows you to change the values of variables used
in the simulation, such as G and DT.
-- The Masses view, which allows you to create and delete masses, and change
their individual settings.
-- The Examples view, which allows you to load pre-created examples, save
examples you have created or edited, and import and export examples from/to the
iPhone pasteboard to share with other Nbody users.
-- The Info view, which shows this user's manual.
-- Zoom in (at upper right). Tap to increase the magnification (make bigger)
of the display.
-- Go/stop (outer button at lower right). Tap to start or stop the simulation.
-- Reset (inner button at lower right). Tap to reset all masses to their
original positions, erase all trails, and set the simulation time to zero.
-- Potential energy in Joules (middle). Following the standard convention, the
gravitational potential energy shared between all masses is a negative value,
and only becomes zero if all masses are removed to infinity.
-- Kinetic energy in Joules (at right).
1. The point x = y = z = 0.
2. The center of mass of all masses (centroid).
3. The center of any individual mass (sometimes called 'geocentric').
-- A copy of this user's manual.
-- A tutorial on how to create your own Nbody examples from scratch.
-- Additional examples.
-- A detailed description of how to create and edit Nbody examples as text, and
how to import these examples using Safari or Mail.
-- Additional tips about how to get the most out of the Nbody application.
© 2009 Sky Coyote