PHYSICS SIMULATOR 1.0
---------------------

This version of Physics Simulator is freeware and may be freely
distributed as long as all the original files are unchanged and
kept together.

The program has been tested under Windows 95 and 98. Nevertheless,
if you find bugs please e-mail to hjboonstra@home.nl
Suggestions and remarks are also welcome.

(c) Copyright H.J.H. Boonstra, 2001
Use this program at your own risk. The author disclaims anything
that this program may cause.


I. INTRODUCTION
---------------

Physics Simulator simulates the dynamics of particles under the
influence of their gravitational and/or electrostatic interactions.
For a pair of particles of mass, electric charge (m, q) and (M, Q)
and separation r the simulated interation is


      	             m M       q Q         (-G + C q/m Q/M)
             F = -G ----- + C ----- =  m M -----------------
    		     r^2       r^2               r^2


Here G is Newton's gravitational constant and C is usually expressed
as 1/(4 pi epsilon) where epsilon is the electric permittivity.
There is no restriction on the number of dimensions nor on the
number of particles that can be simulated. However, since all
inter-particle forces are calculated, the simulation will ultimately
slow down quadratically with the number of particles.



II. GETTING STARTED 
-------------------

You can either start to construct a new particle configuration or
load an already existing set-up. Set-up files have default file
extension ".pss". A few example set-ups are provided.
Once a particle set-up has been loaded or created, the simulation
can be run using the navigation buttons on the right of the main
window or through the Simulation menu. It is possible to run the
simulation backwards in time and also to have it proceed step-wise.
When the simulation is stopped, it is reset to its initial
configuration.

To build up a new set-up choose New from the File menu. A name for
the set-up and the number of (space) dimensions are then asked for.
There are no severe restrictions on the number of dimensions: it must
be at least 1. (Why restrict the number of dimensions when it's
not really necessary?)
Next, particle data should be inserted. Several particle properties
can be specified, among them the mass, charge and initial (time t=0)
position and velocity. These are used to compute the trajectories,
starting at t=0. The radius is used in the simulation if collision
detection is turned on.
The mass property of a particle may be left zero if its charge also
vanishes, corresponding to a massless test-particle probing
the gravitational field whilst not influencing it.

The program does not use any predefined units of mass, distance etc.,
so it is up to the user to choose units. The edit boxes throughout
the program have a built-in parser which may be helpful if one needs
to convert between units. You can define constants that can be used
in all edit boxes. Pre-defined constants are
     Newton's constant        GN     in m^3 / (kg s^2)
     permittivity of vacuum   E0     in Farad / m
     elementary charge        QE     in Coulomb

The particle's image is a disc whose radius and colour can be changed.
One can also choose to have the particle's trail drawn or to make
the particle invisible so that only its influence on other particles
may be seen.

You can make notes to a particular particle configuration using Notes
from the Edit menu. They are saved together with the particle set-up
and simulation and frame settings.


III. SIMULATION OPTIONS (menu Edit|Simulation options)
-----------------------

Several integration methods have been implemented. The most
straightforward one is the Euler method which is only included to
demonstrate how much better the other methods are.
Apart from the numerical method one should specify the time step
of integration. The smaller the time step the more accurate and slower
the simulation will be. The RKF integration method, however, determines
its own time step (starting from the initial user-provided one). It is
the most efficient of the methods implemented but it doesn't give a
good impression of speeds since it slows down when objects are close
together. The accuracy of the RKF method can be influenced through the
accuracy setting which can be found below the list of numerical methods
on the Simulation options dialog window.

The number of computation cycles is the number of time steps computed
before anything on the screen is updated. It can be changed to
influence the speed of the simulation, but not the accuracy.

It is possible to have collisions between particles detected by
selecting this option on the Simulation Options screen. The detection
is based on the radii of the particles and not on the size of the
paricles as they appear on the screen. When a collision occurs the
simulation is stopped.

The coefficients of the gravitational and electrostatic forces can
be altered to fit one's own system of units. By setting the
coefficient of Coulomb's force (C in equation (1)) to zero, a
purely gravitational simulation is obtained.
It is also possible to change the inverse square power of r in (1). 


IV. FRAME SETTINGS (menu Edit|Frame settings)
------------------

The view frame can be modified in several ways. First, one can select
the two-dimensional projection to be shown by associating two space
coordinates with the screen's horizontal and vertical axes.
The scale can be set via the pixels per unit length setting, which is
the number of screen pixels representing one length unit of the
simulated system. It can also be altered using the zoom buttons.
The origin of the view frame can be set on the Frame settings screen
or using the arrow keys.
The frame can be centered on the origin of the system's coordinate
frame, on the center of mass or on any of the particles in the system.


V. FURTHER OPTIONS
------------------

If "Display info" in the Options menu is checked, a small window will
be on top displaying a summary of several charateristics of the
particle configuration. Shown are the current numerical method and
time step, total kinetic and potential energy and the conserved
quantities total energy, momentum and angular momentum. If the
simulation doesn't conserve the latter quantities very well, a smaller
time step (accuracy in case of the RKF method) may have to be chosen
in order to improve the accuracy of the simulation.

Particles' trails can be drawn. The choice is: draw all trails,
draw only the trails of particles whose "Show trail" property has been
set or draw none of the trails.

Finally, the center of mass can be marked/unmarked by
checking/unchecking "Show center of mass" in the Options menu.
