User's Manual for Nbody version 1.0 application for the Apple iPhone

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:

1. Introduction
2. Motion view
3. Settings view
4. Masses view
5. Examples view
6. Info view

1. Introduction

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.
-- 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.

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.

2. Motion view

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.
-- Zoom in (at upper right). Tap to increase the magnification (make bigger) 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.
-- 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.

Three numbers are displayed at the top of the screen:

-- Simulation time in seconds (at left).
-- 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).

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.

3. Settings view

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:
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').

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.

4. Masses 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.

5. Examples view

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.

6. Info view

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.
-- A copy of this user's manual.
-- A tutorial on how to create your own Nbody examples from scratch.