JOrrery

N-body Simulation

Author: John Taylor


Quick Start

JOrrery simulates the motion of planets moving under gravity. It comes with a number of initial "scenarios" you can run, such as "The solar system", "Earth & Moon" etc and you can load and save your own scenarios in xml format. You can also add more planets during a simulation. JOrrery allows you to create a number of different views on the universe, either as graphical views focussed on different planets, or text views giving the planets coordinates in space.

Instructions for use

The applet starts up with the built-in Inner Solar System Scenario which shows the planets Mercury, Venus, Earth and Mars orbiting a (rather small) sun.

Changing Scenarios

The Scenarios menu offers several other pre-loaded scenarios. These are described more fully below.

New Views

Four types of "View" are available from the buttons at the bottom left of the applet. Time views show the elapsed time since you started the applet (massively accelerated of course), Text Views allow you to examine the (x,y) coordinates of any planet, while Graphical Views are similar to the view area of the centre of the applet and show the planets moving around the universe. New! Trails view plots the course of a planet over a period of time relative to the centre of the view. Focussing the view on Earth, you can clearly see the retrograde motion of the superior planets as the Earth overtakes them.

Each View has a properties button allowing you to edit features of the view such as the rate of frame update (if your PC is struggling a bit you might want to try slowing this down). Graphical Views can be zoomed in and out, and either centred on the origin of the system, or made to track a particular planet.

Adding New Planets

The "New Planet" button adds a randomly place planet in the system. It's not a particularly useful way to add a planet because you have almost no control over what happens - as often as not the planet doesn't have sufficient velocity to maintain its position and simply drops into the sun. However, you can exert some control via the Settings/Planet Creation menu item which allows you to select the colours of the planet, its maximum velocity and mass etc. Note that if you have "random mass" set to true, the newPlanetMass indicates the maximum mass the planet could have, otherwise the given mass is used as-is.

Changing the algorithm

The Settings menu offers a number of options for controlling the algorithm:

Clock Properties changes the time step (in seconds) in the simulated universe. Smaller timesteps mean the planets will move more slowly and the calculation should be more accurate. You can also change the number of (real) milliseconds between each step of the algorithm - few milliseconds mean your computer does the calculations faster, but performance elsewhere (such as refreshing the views) might suffer.

Algorithm properties allows you to change the gravitational constant, the distance power used on the graviational equation (set this to one more than you want, ie standard, inverse square law = 3) and the so-called relaxation parameter (simply adds a small constant to all distances to avoid divide by zero problems when two planets get too close).

New features in 1.2

In addition to the new trails view and the new 3-body scenario JOrrery now has the ability to load and save scenarios.

Loading and saving scenarios in xml

The scenarios menu now has an option to load and save scenarios in xml format. Due to security restrictions preventing applets reading and writing to your local disk, you will need to actively enable this feature on your machine. (See security settings below).
The locations of the loaded/saved files are specified in the settings/file locations menu item. Unfortunately, java applet security restrictions prevent the applet showing a proper file load/save dialog since this would require access to all of your local disk, so you have to type your file locations yourself. You need to give two files, one to contain the physical information about the scenario, the other to contain graphical information such as the colours and shapes of the planets. Try saving a built-in scenario to see the formats of the files that are required.

Security Settings

Java applets are not allowed to write to your local disk, and with good reason. However, you can allow certain applets to have certain restricted permissions to certain restricted areas of your disk by supplying a policy file. The example policy file below should be saved somewhere on your local disk.
/* AUTOMATICALLY GENERATED ON Tue Dec 11 15:40:55 GMT 2001*/
/* DO NOT EDIT */

grant {
permission java.io.FilePermission "c:\\jorrery\\*", "read, write";
};

As you see, the file grants read and write permission for the applet to a single directory (c:\jorrery), which you should create. Note that it does not allow the applet to execute anything on your disk, which is important, otherwise it could quite merrily save a malicious program in this folder and then run it.
Finally, you need to tell Java about the existence of this policy file. Find the folder in which you installed the java plug-in (e.g. d:\java\JavaSoft\jre). Somewhere buried underneath this folder will be a security folder containing a file "java.security". Open this in a text editor and find the lines which are something like
# The default is to have a single system-wide policy file,
# and a policy file in the user's home directory.
policy.url.1=file:${java.home}/lib/security/java.policy
policy.url.2=file:${user.home}/.java.policy

and add the line
policy.url.3=file:d:/tbu/dev1/jdt/com/johndavid_taylor/nbody/jorrery.policy
obviously changing the above path to the location where you saved your jorrery.policy file. Restart your browser and hopefully you will be able to load and save, provided you are trying only to access the c:\jorrery folder. If you get a message complaining about security settings then it's possible you've edited the wrong java.security file. Often there are several almost identical ones on a PC and it might be worth trying to change them all.

About the built-in scenarios

The build-in scenarios are reasonably close to real life - the distances between the planets are correctly to scale and the relative sizes of the planets are generally to scale. The planets periods should be reasonably close to reality. However, due to the vast size of space I've had to make a few compromises - the sizes of the planets are not to scale with the distances between them. As a result in some scenarios (such as the whole solar system) some of the planets seem to be rubbing shoulders with the sun, and indeed the inner planets are orbiting inside it! This was the only way that the planets and sun could be made visible when the whole solar system was in shot - it gives you an idea of just how empty the solar system is. In two of the scenarios (Solar System (sun not to scale) & Inner Solar System (sun not so scale)) the Sun has been made much smaller than it should be simply to give the planets a chance to show up. Try the scenarios where the sun is to scale and try to find Mercury to see how vast the Sun is compared to everything else.

The scenarios are:

  1. Earth-Moon - showing the Earth and Moon orbiting about their common centre of gravity (notice the wobble in the Earth) every 4 weeks or so.
  2. Inner Solar System (sun not to scale) - Sun, Mercury, Venus, Earth, Mars, with the Sun shrunk to about Earth diameter.
  3. Inner Solar System (sun to scale) - Sun, Mercury, Venus, Earth, Mars, with the Sun actual size - you'll have to zoom in to see any planets
  4. Solar System (sun not to scale) - everything out to Pluto, with the Sun shrunk to about Jupiter diameter
  5. Solar System (sun to scale) - the same with the Sun the correct diameter (relative to the planets)
  6. Two identical Earth-sized planets roughly Earth-Moon distance apart
  7. Three identical Earth-sized planets in an orbit about their common centre of gravity. Note that this orbit is unstable and deteriorates after time.
  8. A blank canvas!

About the program

JOrrery illustrates the Model-View-Controller pattern. The Model is the underlying algorithm solving the motions of the planets. The Views are the graphical windows which interpret the data processed by that algorithm and display it as moving circules, or whizzing numbers.

The applet makes extensive use of BeanPeelers for the property editors.

The source code is available, but rather untidy. Let me know if you use it - it's nice to know there are people out there.

[More on the program to appear.]

About the mathematics

JOrrery uses a simple leap frog method to solve the equations describing the gravitational interaction of the planets (the so-called N-body problem.) The trick with solving n-body problems is to devise a numerical method which simulates the system and keeps the total energy of the system constant - otherwise your planets gradually fly off into the wide black yonder. Leap-Frog is the simplest method to do this, though it's not sufficiently accurate for serious simulations. [More on the mathematics to appear.]

Future Developments for 1.2


Back to JOrrery

Back to programs page

Back to home page